Sanctions Screening

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: the default free model (Workers AI Llama-3.3-70b), the BYO-API-key cost implication ('you pay Anthropic directly'), and that the key is 'passed straight through to api.anthropic.com'. This goes beyond the annotations to disclose external costs and key handling.

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

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

The description is four sentences, front-loaded with the core function, then operational details (default model, key behavior, return structure), and ends with use cases. Every sentence contributes new information; no filler or redundancy.

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

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

Given no output schema, the description compensates by explicitly listing the return shape: 'per-model {score, confidence, signals, raw_response} + a combined view.' It also covers defaults, cost implications, and use cases. This is complete for a probing tool with 4 well-described params and rich annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying the default model, that _apiKey is required only if 'anthropic' is in models, and that context helps disambiguate common names. This supplements the schema's per-field descriptions.

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

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

The description opens with a specific verb+resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It clearly distinguishes the tool from siblings like ask_pipeworx and scan_competitor_ai_presence by focusing on model-agnostic AI visibility scoring.

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

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

The description provides clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly name alternatives or when-not-to-use, but the context is sufficient for an agent to infer appropriate scenarios. Sibling tool names suggest overlap with scan_competitor_ai_presence, but no explicit differentiation is given.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses how the tool behaves: it routes the question, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier in one fast call. This provides substantial behavioral context without contradicting any annotations.

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

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

The description is long but well-structured, starting with the key directive 'PREFER OVER WEB SEARCH' and then logically covering purpose, triggers, examples, and alternatives. Every sentence adds value, though some redundancy exists (e.g., 'START HERE' and 'default entry point' could be condensed). Overall, it earns its length by being densely 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 that there is no output schema, the description compensates by specifying the return format ('structured answer with stable pipeworx:// citation URIs'), the breadth of data domains (SEC, FDA, FRED, etc.), and the tool's role as the default entry point. It also covers edge cases like breaking news routing, making it comprehensive 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 input schema already describes the sole 'question' parameter and its five aliases with examples, giving 100% schema coverage. The description adds no new information about parameters—it only provides usage examples, which are also present in the schema. Thus, the baseline of 3 is appropriate; the 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 clearly states that the tool answers factual questions about current/historical data by routing to over 5,439 tools across 1,412 sources and returning structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different use cases, so the purpose is specific and differentiated.

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 this tool, starting with 'PREFER OVER WEB SEARCH' and 'Use whenever the user asks...' It also gives when-not-to-use guidance by directing users to ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, along with examples for concrete triggers.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses its experimental nature, that live candidate routing improvements may be active, and that no candidate is currently active as of 2026-07-26, making it functionally identical to ask_pipeworx. It also clarifies it is a full working router with no fallback.

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 4-sentence, front-loaded explanation covering purpose, current state, usage, and operational semantics. Each sentence adds value, though it is slightly verbose with repetitions like 'same arguments, same response shape' that could be trimmed without losing meaning.

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

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

The description provides complete context for a beta tool: what it is, current state, relationship to the stable sibling, and what happens with results. Since it explicitly references ask_pipeworx for exact behavior and response shape, the lack of an output schema is compensated by pointing to the stable tool.

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

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

The input schema fully documents all 6 parameters with 100% coverage, including the question parameter and its aliases. The description adds no parameter-specific detail beyond stating 'same arguments' as ask_pipeworx, so it contributes little beyond what the schema already provides.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, an identical universal router with the same 5,439 tools, arguments, and response shape, but with candidate routing improvements. It distinguishes itself from the stable ask_pipeworx sibling by framing itself as the experimental edge.

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

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

The description explicitly instructs to use it exactly like ask_pipeworx when you want the newest routing, and mentions results are compared against the stable router. It also clarifies that when no candidate is active (currently the case), it matches ask_pipeworx exactly, providing clear decision context.

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

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

Beyond annotations, the description discloses refusal behavior (refusal_reason values), return fields, the use of only tool result content, and the extra LLM call cost. It adds substantial behavioral context without contradicting annotations.

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

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

Every sentence earns its place: the mode is defined, the mechanism is explained, return/refusal formats are listed, usage context is given, and the tradeoff vs sibling is stated. Well-structured and not bloated.

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

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

Despite no output schema, the description fully explains return values and refusal reasons. It covers behavior, failure modes, and alternatives, making it complete for a tool with this complexity.

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

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

The schema is fully self-explanatory with 100% description coverage for all six aliases of 'question'. The description adds no parameter details, but the schema already handles this, so the baseline 3 applies.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode that extracts answers using only tool result content. It distinguishes from sibling ask_pipeworx by noting the same routing but grounded extraction and higher cost.

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

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

Explicit usage guidance is provided: use for high-stakes reads where quoted/cited/acted-on answers are needed, and prefer ask_pipeworx for casual lookups due to the extra LLM call cost. This clearly differentiates from siblings.

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

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

The description goes far beyond the readOnly/idempotent/openWorld annotations by disclosing specific behaviors: parallel fan-out to category-specific data packs, low-confidence match short-circuiting, closed/inactive market status suppression, wide-spread illiquidity flags, news fallback behavior, and the resolution-rule risk around cancellations and 50¢ void settlements. This is rich, actionable behavioral context that helps the agent trust and safely use results.

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

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

The description is long but front-loads purpose and uses CAPS-labeled sections and concrete fan-out examples. It is structured enough to navigate, and most details serve a purpose for a complex tool with no output schema. A minor deduction because some sections (e.g., resolver contract and resolution-rule risk) could be tightened without losing essential 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 no output schema, the description must carry the full burden of explaining return shapes, and it does so comprehensively: result.market fields, result.analysis including edge/model probability and 24h-move warning, result.evidence organization, resolver contract fields, parent_event extractor, news fallback fields, and status conditions. It covers edge cases and gives concrete safety guidance for fuzzy matches and closed markets.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaningful parameter-level semantics beyond what the input schema already provides; e.g., it repeats the market slug/URL/question format that is already documented in the schema. It does not clarify depth or include_raw beyond their existing descriptions.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clarifies the input (slug, URL, or question text) and explains the resolution/classification/fan-out pipeline, which distinguishes it from sibling tools like polymarket_edges or ask_pipeworx by focusing on comprehensive market research rather than simple queries or edge tracking.

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 gives usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete fan-out examples across bet types. However, it does not name alternative tools or explicitly state when NOT to use this tool, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and the description adds valuable behavioral context without contradicting them: data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorting by primary metric, and the inclusion of pipeworx:// citation URIs. This goes beyond annotation basics.

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

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

The description is dense but every sentence earns its place: it front-loads purpose with examples, then provides usage guidance, technical details, and output expectations. No redundancy or filler; 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?

The description covers purpose, triggers, alternatives, type-specific behavior, sorting, and output format (paired data + citation URIs). Given the tool's complexity and absence of an output schema, this is fully complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, but the description significantly enriches parameter meaning. It clarifies what type="company" vs type="drug" returns (specific financial metrics vs trial/adverse-event counts) and what values should contain (tickers/CIKs vs drug names). This is essential semantic detail not present in the schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one parallel call, with concrete trigger examples ("X vs Y", "which is bigger"). It explicitly distinguishes itself from sequential single-pack lookups and sibling tools like entity_profile, making its purpose unambiguous.

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

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

It gives explicit when-to-use guidance: "ALWAYS PREFER over sequential single-pack lookups when comparing entities." It also specifies what each entity type does (company vs drug) and even mentions 'Replaces 8–15 sequential lookups,' providing a strong alternative comparison and context for use.

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

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

Beyond the annotations, the description discloses account requirements, plan limitations for depth 'thorough', timeout expectations (15-60s up to ~90s), gap handling (never invents, returns gaps[]), contradiction detection, semantic excerpting, and citation formats. It clarifies that it is not open-web search despite the openWorldHint annotation, adding important context.

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

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

The description is long but information-dense, front-loading the most critical account requirement and key differentiator. It uses headers-like phrases and examples, but every sentence adds value; it's verbose but not wasteful.

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

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

Given no output schema, the description thoroughly explains the return format (findings packet, citations, gaps[], contradictions[], hop field). It also covers performance expectations and depth semantics. The complexity of the tool justifies this level of detail, and no critical operational aspect is omitted.

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 at 100% coverage. The description adds practical context: depth levels map to hop counts and plan requirements, and question examples illustrate acceptable inputs. This exceeds the baseline, though much is redundant with 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 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources' and explains the decomposition/parallel routing behavior. It also contrasts with ask_pipeworx, making the tool's unique scope explicit.

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 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', giving alternative tools and when-not-to-use instructions. Also notes account prerequisites and the alternative for non-signed-in users.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral detail about the return value: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes 'no second schema lookup needed.' This exceeds what annotations provide, though it omits things like pagination or rate-limit behavior.

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

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

The description is three sentences, each serving a distinct purpose: (1) core function, (2) when to use with domain list, (3) return behavior and first-call recommendation. It is front-loaded with the verb+resource and every sentence earns its place without fluff. The density of useful information per word is high.

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

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

There is no output schema, so the description correctly assumes the burden of explaining the return format ('names, descriptions, and full input schemas'). It also covers the key usage context ('Call this FIRST'), and the parameter schema handles the rest. For a tool discovery utility, this is complete: an agent knows what it does, when to use it, and what to expect back.

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 coverage is 100%, with all parameters (query plus aliases q, task, search, description, and limit) clearly described in the schema itself. The description adds no parameter-specific semantics beyond saying 'describing the data or task,' which is already implied by the schema's 'query' description. Baseline 3 is appropriate when schema carries the load.

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 'Find tools by describing the data or task' which clearly states the tool's function as a discovery mechanism. It distinguishes itself from sibling tools by emphasizing browsing/searching for available tools rather than performing a specific domain task, and it enumerates the coverage areas (SEC filings, FDA drugs, etc.) making the purpose unambiguous.

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

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

The description gives explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly tells the agent when to invoke it but does not explicitly name alternatives or provide when-not-to-use exclusions, stopping short of a 5.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses concrete behaviors: parallel fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; patents API sunset with soft-fail; GDELT→GNews fallback; and return field specifics. These are non-obvious dynamic behaviors that annotations don't cover, so the description adds significant value.

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 the description is a single dense paragraph, it packs in usage examples, cross-source details, output fields, fallback behavior, and input constraints. It is information-dense but well-structured with semicolons; however, it could be broken into sections for readability, so a 4 rather than 5.

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

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

For a tool with no output schema, the description thoroughly enumerates all return components (CIK, company name, filings with URIs, fundamentals, patents, news, LEI). It also explains the sunset and fallback behavior. This is comprehensive for the tool's complexity.

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

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

Schema coverage is 100%: both type and value have descriptions with examples and constraints. The description largely restates the same information ('ticker or zero-padded CIK', 'names not supported') without adding new parameter-level semantics. Thus baseline 3 is appropriate.

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

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

The description opens with numerous example user intents, then explicitly states its function as 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools by emphasizing 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' This leaves no ambiguity about what the tool does.

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

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

Provides explicit guidance: prefer this tool for holistic views rather than chaining individual lookups. Also tells users to use resolve_entity first if they only have a name, establishing a clear alternative. This is exactly the kind of when/when-not guidance that helps agents select correctly.

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 destructiveHint (true) and idempotentHint (true), so the safety profile is known. The description adds usage context but no additional behavioral traits beyond what annotations convey, such as irreversibility or error behavior.

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

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

The description is three sentences, each with a distinct purpose: action, usage, and related tools. No redundant words, front-loaded with the primary operation.

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

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

The tool is simple with one required parameter, annotations cover destructive and idempotent behavior, and the description provides purpose and usage. No output schema needed; the description is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100% with a clear description 'Memory key to delete' and an example. The description repeats 'by key' but adds no new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb and resource. It distinguishes from siblings by explicitly positioning itself as the memory deletion counterpart to remember and recall.

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

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

The description provides explicit usage scenarios ('context is stale, the task is done, or you want to clear sensitive data'), giving clear context. It does not explicitly state when not to use or name alternatives, but mentions pairing with remember and recall.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses the fetch-and-extract process, the emission of standard markdown, and the ready-to-drop output blob. This adds meaningful behavioral context without contradicting any annotations.

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

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

Three tight sentences: purpose/audience, process/output, and use cases. Every sentence earns its place, with the most essential information front-loaded in the first sentence.

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

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

For a simple two-parameter tool with no output schema, the description fully covers what the tool does, what output format to expect (single text blob in llms.txt markdown), and why it is useful. No critical context is missing.

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

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

Schema coverage is 100% with both parameters (url and max_links) fully described, so the baseline is 3. The description does not add parameter-specific semantics beyond what the schema already provides, but it also does not need to.

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It clearly defines the tool's output and distinguishes it from siblings by framing it for AI crawler indexing and competitor auditing.

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 'Useful for:' clause explicitly enumerates three concrete scenarios: indexing a client's site, drafting your own llms.txt, and auditing a competitor. It gives clear context, though it does not explicitly name alternative tools or state when not to use this tool.

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

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

With annotations already marking this as readOnly and non-destructive, the description adds behavioral context by specifying the scope (caller's subscriptions) and enumerating the returned fields (id, type, params, created_at, last_fired_at, fire_count). It also clarifies that inactive subscriptions are excluded by default, matching the include_inactive parameter.

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

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

Two sentences, front-loaded with the core purpose, and the second sentence provides return details and use guidance. 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?

The tool is simple with one optional parameter and no output schema. The description covers the core action, return fields, and usage context. It's sufficiently complete for its complexity, though it could explicitly mention the relationship with subscribe/unsubscribe tools for full context.

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

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

Schema coverage is 100% with the include_inactive parameter having a full description. The tool description does not add additional parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description uses the specific verb 'list' and identifies the resource as 'the caller's active subscriptions', clearly distinguishing it from sibling tools like subscribe and unsubscribe by focusing on the read-only listing aspect.

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

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

The description explicitly states when to use it: 'to review what you're monitoring before adding more or to find an id to cancel'. This gives clear use cases and implies alternatives (subscribe/unsubscribe), though it stops short of explicitly naming them.

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

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

Annotations provide no safety hints, but the description discloses important behavioral details: rate-limited to 5 per identifier per day, free and not counted against quota, team reads digests daily, and feedback signal affects roadmap. It also tells users not to paste end-user prompts, which is a useful behavioral norm beyond what annotations offer.

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

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

The description is longer than ideal but every sentence carries purpose: it defines scope, gives usage timing, states exclusions, provides format guidance, and mentions rate limits. There is no filler or repetition of schema content, and the most critical use-case guidance is front-loaded.

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

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

For a feedback tool with no output schema and moderate parameter complexity, the description is complete. It covers what to report, how to format it, where to file it, rate limits, and the impact of feedback. The nested 'context' object's purpose is also implied by the description's guidance to reference Pipeworx tools/packs, making the tool actionable for an AI agent.

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

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

Schema description coverage is 100%, so parameters are well documented. The description adds semantic value for the 'message' parameter by instructing users to describe issues in terms of Pipeworx tools/packs and to avoid pasting the end-user's prompt. It also clarifies the meaning of the 'type' enum values indirectly through usage scenarios, supplementing the schema descriptions.

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

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

The description opens with a clear, specific verb plus resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes itself from sibling tools by being the unique feedback channel for this MCP server, and the tool name matches the description without tautology.

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

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

The description explicitly lists when to use the tool ('Use when a tool returns wrong/stale data... feature/data_gap... praise') and when not to use it ('if the tool came from a different MCP server... file it with that server instead'). It also gives a concrete disambiguation rule ('Pipeworx tool names are the ones this connection lists'), which is strong 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?

Beyond annotations, the description adds important behavioral context: data source (CF analytics-engine), privacy (no PII), aggregation details, and caching (5min-1h). It also specifies return values, giving the agent a clear picture of what to expect without an output schema.

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

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

The description is well-structured and front-loaded: a one-line purpose, a returns statement, a numbered list of use cases, and a final sentence on data source/caching. 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?

For a simple tool with one optional parameter and no output schema, the description covers purpose, return values, use cases, data provenance, privacy, and caching. Annotations provide safety profile, making the description contextually complete.

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

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

The schema already fully describes the only parameter 'window' with enum values and meanings. The description merely references the window options without adding new semantic detail. Given 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the resource (Pipeworx trending data) and specific outputs (top tools, top packs, total call volume). It differentiates from siblings like discover_tools by emphasizing "what other AI agents are calling right now" and the self-aggregating nature, making its purpose distinct.

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

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

The description provides explicit use cases (discovering hot data sources, confirming canonical tools, aligning with agent needs), which is clear context for when to use it. However, it does not explicitly name alternatives or exclude scenarios, so it stops short of full when/when-not guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses significant behavioral details: it filters placeholder slugs, returns null signals for partitions with >20% placeholders, and performs a fill check against live CLOB depth with explicit guidance ('realizable_edge_pp ≤ 0 ... do not trade it'). It also mentions skipped_low_similarity counts, giving agents a clear picture of failure and edge-case behavior.

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

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

The description is dense but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence earns its place by providing actionable information. Front-loading the purpose and invocation modes makes it easy to parse quickly.

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

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

Given the tool's complexity and absence of an output schema, the description covers the response structure (opportunities[], partition_check fields), trade signals, and warning conditions. It also contextualizes against sibling tools, making it sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains event slug formats, accepts full URLs, provides concrete examples, and details how each parameter changes the scan scope and behavior. The semantic anchor and partition filter details directly inform how parameters are interpreted.

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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from siblings by explicitly mentioning polymarket_fill_risk for custom sizing and outlining three distinct invocation modes (trending_scan, event, topic), which differentiates it from other Polymarket tools.

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

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

The description provides explicit when-to-use guidance: no args for trending scan, event for specific markets, topic for cross-event scanning. It also explains when to use an alternative tool ('For custom sizing use polymarket_fill_risk') and describes the trade-off between event and topic modes, including what cross-event mode catches that single-event misses.

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

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

Annotations already mark the tool as read-only and non-destructive, but the description adds extensive behavioral context: detailed model family calculations, net-of-slippage edge, Kelly caps, 24h-move warning, placeholder-slug filtering, caching behavior, and diagnostics. It even discloses the 25:1 portfolio return threshold and that concentrated longshots are rare-by-design. This goes far beyond the safety hints.

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

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

The description is long but densely packed with essential details, and the opening sentence front-loads the core purpose. Each sentence carries operational value, from model families to response structure to diagnostics. It could be slightly trimmed (e.g., the per-sport alpha list), but it remains purposeful and not tautological. The use of ALL-CAPS headers improves scanability.

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 specifies the response shape: by_segment with three segments, fed_candidates/fed_note, and _diagnostics with funnel counters. It also details what each opportunity includes (edge_pp_net, kelly_fraction, market.liquidity, spread_pp, volume, 24h warning). This is a complete picture for an agent to interpret results and handle empty segments via diagnostics.

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 all 9 parameters. The description adds valuable cross-parameter semantics: e.g., min_kelly never applies to partition_overround because parent kelly_fraction_half is always 0, so the separate min_partition_leg_kelly knob is needed. It also explains the tradeable-edge filters (min_liquidity, max_spread_pp) and the interplay of slippage_pp with edge_pp_net, adding meaning beyond the schema.

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

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

The opening sentence specifies the verb 'Scan' and resource 'top Polymarket markets', and clarifies the unique purpose: returning opportunities where Pipeworx data disagrees with market price. It also differentiates from siblings like polymarket_arbitrage by framing itself as the discovery tool for 'what should I bet on today', avoiding the need to page through hundreds of markets.

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

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

The description clearly frames when to use this tool ('what should I bet on today', discover opportunities without paging). It also provides contextual exclusions, such as Fed bets being excluded from ranking due to unreliable signals. However, it does not explicitly name alternative tools or state when to use them instead, leaving implicit differentiation.

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

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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses critical behavioral traits: snapshot TTL limits (60-day), snapshotting enabled only on cache-miss, gaps meaning no scan occurred, decay computed from daily closes not intraday, and the signed nature of edge_pp_net. This substantially aids the agent in interpreting results and limitations.

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

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

The description is structured into clear sections: core purpose, the question it answers, argument definitions, response format, and limitations. Despite its length, every sentence provides necessary operational detail, and the purpose is front-loaded. It demonstrates concise organization for a complex telemetry tool.

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

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

With no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates), key fields (edge_pp_net time-series, trend, decay_pp_per_day, lifespan_days), and critical caveats (TTL, scan gaps, daily closes). This is complete enough for an agent to use the tool effectively without additional documentation.

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

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

The schema already covers both parameters with descriptions (100% coverage), and the description adds semantic context by calling days a 'lookback' and window a 'snapshot family', plus clarifies default/max values. This goes beyond the schema's basic descriptions, justifying a score above baseline.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, with a specific verb ('track') and resource ('edge persistence/decay'). It distinguishes itself from sibling tools like polymarket_edges by focusing on historical dynamics, answering 'how long has this edge existed and is it shrinking?' rather than just listing current edges.

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

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

The description gives strong contextual guidance, explaining that a fresh wide edge and a 3-week-old wide edge are 'different trades', which signals when to use this tool versus looking at current edges. It doesn't explicitly name alternatives like 'use polymarket_edges for current edges', but the contrast is implicit and clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the bar is lower. The description adds rich behavioral detail: it walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), and discloses the danger of partial fills converting an arb into unhedged directional exposure.

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?

Although dense, every sentence earns its place. The structure uses caps and semicolons to separate modes and returns a comprehensive list of outputs. It is appropriately sized for a complex tool with two modes.

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

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

The description covers both operating modes, all inputs, detailed return fields, edge cases (thin_legs, forced_directional_risk), and the risk rationale. With no output schema, it fully describes expected outputs and verdicts, making it self-sufficient for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% with descriptions per parameter, but the tool description greatly extends semantics. It explains the two modes (single-market vs basket), how 'side' defaults differ by mode, how size_usd is interpreted (spend vs target proceeds vs settlement notional), and clarifies the output fields that map to each mode.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a specific verb+resource that clearly identifies the tool's purpose. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by framing itself as the pre-trade risk check.

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

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

Provides explicit usage direction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the failure mode (partial basket fills become directional risk), giving clear when-not and why.

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

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

Despite annotations already declaring readOnly/idempotent/destructive=false, the description adds substantial behavioral detail: response components (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning with two specific trigger cases), temporal_alignment semantics, and skipped_cross_type/subtype counters. It explicitly warns that most pre-mapped topics are not tradeable, revealing real-world behavior beyond any structured field.

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

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

The description is long but densely packed with essential information and follows a clear logical structure: purpose → modes → response → safety fields → caveat. Every sentence contributes functional value, and the final warning about pre-mapped topics prevents user misunderstanding. 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 carries full responsibility for explaining return shape and edge cases. It enumerates response components, defines compatibility_warning scenarios, explains temporal alignment, and describes skip counters. For a tool with this complexity, the description is remarkably complete and actionable.

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 three params documented), and the description enhances semantics by explaining the two-mode interaction: topic shortcuts auto-fetch both sides, while explicit ticker/slug override the topic-mapped side. It adds context about which parameters work together and what 'pre-mapped' means, going beyond the raw 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 opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage by emphasizing that pre-mapped ≠ tradeable and through the compatibility_warning semantics.

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

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

The description clearly explains two usage modes: using pre-mapped topic shortcuts or providing explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It gives realistic guidance about when spreads are meaningful and warns that most pre-mapped topics return compatibility_warning. However, it does not explicitly name alternative tools or state when to prefer a sibling, so it lacks full exclusion guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by explaining the scoping mechanism ('Scoped to your identifier — anonymous IP, BYO key hash, or account ID') and the dual behavior of retrieving one value or listing all keys when the key is omitted. No contradiction with annotations.

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

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

The description is concise and front-loaded, with the first sentence stating the core action and options. Each subsequent sentence adds meaningful context (use case, scoping, relation to siblings) without redundancy or fluff.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description covers purpose, usage context, scoping, and relationships with sibling tools. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema already documents the 'key' parameter and its omission behavior with 100% coverage. The description repeats this (omit the key argument to list all keys) but does not add new parameter-level details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This uses a specific verb and resource, and distinguishes it from sibling tools by explicitly mentioning '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?

It provides clear context for when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names related tools (remember, forget) but does not explicitly state when not to use this tool or provide exclusionary guidance, so it falls short of a 5.

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

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

The description contradicts the readOnlyHint annotation by describing mark_read:true as a state-changing operation ('flag returned events read so the next call only shows newer ones'). This is a direct conflict with the read-only annotation. Even though annotations lower the bar, a contradiction forces a score of 1 per the rubric.

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

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

The description is three sentences, front-loaded with the main action ('Pull fired events'), then details what the events contain, how to filter, and an alternative access method. Every sentence earns its place with no redundancy or fluff.

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

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

Given 5 parameters, zero required, no output schema, and rich annotations, the description covers return contents, filtering, mutation behavior, polling suitability, and even the external URL. It is thorough and self-contained, leaving no major knowledge gaps for an agent.

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

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

Schema coverage is 100% (baseline 3), and the description adds meaningful context beyond the schema: a concrete type example ('sec_8k'), the ISO timestamp format for 'since', and the behavioral effect of mark_read. This enriches the parameter semantics 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 opens with 'Pull fired events from your subscription feed', a clear verb+resource statement that specifies the action and target. It distinguishes the tool from siblings by describing the returned alert structure (source, citation_uri, raw payload) and mentions the same feed is available via a direct URL, clarifying its unique role.

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

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

The description provides practical guidance: how to filter by type and since, the mark_read flag for acknowledgment, and notes that polling works fine. It also points to an alternative HTTP endpoint for scripts/dashboards. However, it doesn't explicitly contrast with sibling tools like 'recent_changes' or 'list_subscriptions', so exclusions are not named.

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 read-only/idempotent/non-destructive, and the description adds substantial non-obvious behavior: parallel fan-out to SEC EDGAR, GDELT→GNews fallback under specific conditions (rate limiting or 5xx), and USPTO patents soft-fail due to API sunset. This goes well beyond the annotations.

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

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

Although dense, every sentence earns its place: intent examples, source list, fallback logic, parameter formats, return structure, and an explicit alternative. Front-loaded with user-facing query phrases, this is efficient and well-structured 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?

No output schema exists, but the description specifies the return shape (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It also covers source edge cases (patents soft-fail, GNews fallback) and parameter guidance, making it 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?

Schema coverage is 100% with each parameter described. The description adds extra value by clarifying 'since' relative shorthand examples and recommending '30d' or '1m' for typical monitoring, plus reiterating ticker/CIK formats. Slight enhancement over 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 this is a change feed for a company over a time window, covering filings, news, and patents. It opens with example queries that define intent and explicitly distinguishes itself from the sibling tool entity_profile (static 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?

It provides direct guidance: use recent_changes for change feeds over a window, and use entity_profile for static profiles. It also recommends typical 'since' values ('30d' or '1m') and explains fallback behavior, making when-to-use very clear.

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

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

The description adds important behavioral context beyond the annotations: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This discloses storage scope and retention behavior, which annotations do not cover. No contradiction with readOnlyHint=false or idempotentHint=true.

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

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

The description is three concise sentences, front-loaded with the core purpose ('Save data...'), followed by usage guidance and behavioral details. Every sentence contributes valuable information 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?

For a simple two-parameter tool with no output schema and good annotations, the description covers purpose, usage, persistence, and pairing. It is fully sufficient for the agent to select and invoke the tool correctly within its context.

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

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

Schema description coverage is 100% with clear descriptions for key and value. The description adds general context about key-value pairs and scoping but does not elaborate on the parameters themselves, so the baseline score of 3 applies.

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

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

The description opens with 'Save data the agent will need to reuse later,' a specific verb and resource. It explicitly differentiates from sibling tools by noting 'Pair with recall to retrieve later, forget to delete,' clearly positioning it against the recall and forget tools.

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

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

It explicitly states when to use the tool: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject) so you don't have to look it up again.' It also names the companion tools (recall, forget) as alternatives, providing clear contextual guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that each call cascades through multiple lookup endpoints, returns specific citation URIs, and auto-disambiguates inputs. This adds meaningful behavioral context about internal complexity and output format.

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

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

The description is longer than average but every sentence is informative, with examples front-loaded and structured by entity type. It avoids fluff and only includes operational details.

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

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

Given no output schema, the description thoroughly explains the return values for each type, including citation URIs and disambiguation. It also covers the tool's internal cascading behavior, making it self-contained for an agent.

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

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

Schema covers both parameters with descriptions, but the tool description enriches them by specifying what each entity type returns and what forms of value are accepted (ticker, CIK, name; brand/generic). It gives concrete examples like 'ozempic' and 'metformin'.

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 resolves user-spoken names to official identifiers, with specific examples ('ticker', 'CIK', 'RxCUI'). It distinguishes from siblings by noting these are required inputs for other tools, and it names supported entity types. Strong verb and resource specificity.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID' and gives query examples. It implies the tool is a preliminary step before other tools but does not explicitly name alternatives or when not to use, so slightly less than perfect.

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, and idempotentHint=true, so the safety profile is covered. The description adds behavioral detail by enumerating the exact fields returned (aliases, addresses, identity documents, programs, etc.), which goes beyond annotations and helps set expectations. 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 two sentences: the first states the purpose and parameters, the second lists the return fields. It is concise, front-loaded, and every sentence adds value with no wasted words.

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

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

For a simple read-only retrieval tool with no output schema, the description adequately covers return values by enumerating fields. It also explains the two input methods and their relationship to sanctions_screen. The context is complete enough for the tool's complexity, though it could mention error behavior or what happens when no entry matches.

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

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

Schema description coverage is 100% with both parameters fully described. The description adds minimal extra value, such as clarifying the uid format comes from sanctions_screen results and that the two parameters are alternatives. This is a baseline 3 because the schema already 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 clearly states the tool's function: retrieving the full Consolidated Screening List record for a single entry by uid or OFAC entity number. It distinguishes itself from the sibling sanctions_screen by specifying the input comes from sanctions_screen results and by emphasizing the full-record return. This is a specific verb+resource+scope with clear differentiation.

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

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

The description implies usage context: use this after sanctions_screen to get full details for a specific entry. It does not explicitly name alternatives or state when not to use, but the relationship to sanctions_screen is clear and the input options are described. This meets 'clear context, no exclusions' level.

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

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

Annotations already indicate this is a read-only, idempotent, open-world, non-destructive operation. The description adds valuable behavioral context by specifying the output content: entry counts and last sync time, which are not visible in the annotations. This goes beyond the minimal credit for annotation-covered traits.

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

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

The description consists of exactly two sentences: the first states the core function, the second provides a use case and examples. It is front-loaded with the main verb and resource, and every word adds value.

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

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

Given the tool's low complexity (no parameters, no output schema), the description sufficiently explains what is returned (entry counts and freshness) and provides concrete examples of the covered lists. This is complete enough for an agent to understand the tool's purpose 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?

The tool has zero parameters, so the baseline is 4. The description appropriately focuses on the output rather than parameters, and no further parameter explanation is needed.

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

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

The description clearly states the tool's function: listing the 12 US restricted-party lists covered by the Consolidated Screening List, with specific output details (entry counts and data freshness). This distinguishes it from sibling tools like sanctions_screen and sanctions_entry by focusing on list metadata rather than screening or entry details.

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

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

The description gives a clear use case ('Use to cite coverage in a compliance report') and provides examples of what is covered, which implies when to use this tool. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context such as fuzzy name matching with a 0-1 relevance score, matched aliases, programs, addresses, list identification, and the empty matches array when clear. It does not contradict annotations.

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

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

The description is a single, dense paragraph that front-loads the main action and packs substantial information (lists, matching behavior, use cases, output behavior) without redundant words. Every sentence contributes value.

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

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

With no output schema, the description compensates by explaining the return format (matches array, relevance score, aliases, programs, addresses, list). It also includes data freshness synced daily, entry count, and use cases. It lacks mention of error handling or edge cases, but is largely complete for a screening 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%, so all five parameters are already documented in the schema with descriptions. The description adds general context about matching and output, but does not add per-parameter details beyond what the schema provides, so it meets the baseline 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 uses a specific verb ('Screen') and identifies the exact resource (person, company, vessel, aircraft name) against the US Consolidated Screening List, listing the specific sublists. It clearly distinguishes from sibling tools like sanctions_entry and sanctions_lists by emphasizing the screening and fuzzy matching aspect.

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 the intended use cases ('Use for KYB / KYC / AML / export-control compliance checks'), providing clear context. It does not explicitly mention when not to use it or mention alternatives, but the purpose is sufficiently distinct from siblings to be inferred.

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 non-destructive. The description adds valuable context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It also hints at external API usage for the Anthropic model via the _apiKey parameter, giving more behavioral detail than annotations alone.

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

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

The description is exactly two sentences plus a short illustrative quote. It is front-loaded with the primary purpose and returns immediately to the use case. Every sentence contributes meaningful information without redundancy or fluff.

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

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

For a tool with no output schema, the description sufficiently explains what it returns (ranked list with score, confidence, signal density), the probing mechanism, and the competitive audit context. It lacks explicit mention of edge cases or network calls, but the schema covers entity limits and the API key, making it reasonably complete.

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

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

The input schema has 100% parameter description coverage, including details on entities (first is subject, rest competitors) and the _apiKey requirement. The description adds no new parameter-level semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It also specifies the mechanism (probes each entity with ai_visibility_check), the ranking behavior, and the use case. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Provides a clear use case: 'Useful for competitive AI-marketing audits' with an example query. It implies the alternative of using ai_visibility_check for a single entity by describing the probing process, but does not explicitly state when not to use this tool or name the alternative as a recommendation.

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 (readOnly, idempotent, non-destructive), the description discloses composite behavior, partial-failure degradation, potential 5-30s latency on first bundlephobia measurement, and the sources_failed field. This adds performance and error-handling context not provided by 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 every clause earns its place: purpose, use cases, return fields, ecosystem scope, and timeout behavior. It is front-loaded with the main purpose and avoids fluff.

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

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

Even without an output schema, the description enumerates the return summary block fields (is_latest, license, advisory_count, etc.), mentions per-advisory details and links, and explains graceful degradation with sources_failed. It also covers ecosystem limitations and version 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?

The input schema documents both parameters with 100% coverage, including scoped-package acceptance and version default behavior. The description adds no extra meaning for the parameters, so the baseline of 3 applies.

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

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

The description clearly states a specific verb+resource: a composite 'should I add this npm package to my project' check that fans out to deps.dev and bundlephobia. It distinguishes itself from sibling tools by limiting scope to NPM and explicitly noting alternative endpoints 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?

Gives explicit usage cues: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also advises where non-NPM packages belong (deps.dev:version directly), helping choose the right path.

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

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

Annotations already mark this as readOnly/idempotent/non-destructive. The description adds rich context beyond annotations: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings with 500-char overlapping windows, and has a 200K char cap with truncation flagging. This is exactly the kind of behavioral detail agents need.

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

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

The description is well-structured: it starts with the core action, then the use case, then complementary tool, then technical details. Every sentence carries information; no fluff. Despite moderate length, it remains tight and front-loaded.

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

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

Given no output schema, the description explains the return shape (passages with offsets and similarity scores). It also covers edge behavior (truncation), technical implementation, and integration with a sibling tool. Combined with clear parameter schemas and annotations, this provides a complete picture.

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

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

Schema coverage is 100% so baseline is 3. The description adds meaning by framing 'text' as 'already pulled' content, clarifying 'query' as natural-language, and explaining the purpose of 'limit'. It reinforces the cap and return format, adding some value beyond the schema.

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

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

The description states a specific verb+resource: 'Semantic search INSIDE a fetched record', clearly distinguishing it from sibling tools like ask_pipeworx_grounded. It also contrasts with whole-document grounding, making the tool's unique scope explicit.

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

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

Explicit guidance is given: use when the record is too big to cram into the prompt. It also pairs with ask_pipeworx_grounded (fetch with gateway, ground over relevant passages), and gives concrete examples of input text. Alternatives and complementary tools are named.

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

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

Annotations already mark this as mutating and idempotentHint=true. The description adds valuable behavioral context: return of the subscription id, OAuth requirement, phone verification, 10/day SMS cap, and feed always-on behavior. It does not contradict annotations, but it stops short of disclosing all details (e.g., webhook auto-disable) which is covered in schema.

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

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

The description is densely packed but front-loaded with the purpose, then auth, types, and delivery channels. Every sentence serves a purpose. It is a bit long, but the complexity of the tool (3 params, nested objects) justifies the length.

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

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

The description covers many aspects—auth, return value, examples, channels—but it states 'Supported types' and lists only three of the five enum values, omitting patent_grant and clinical_trial. This could confuse an agent into thinking those types are unsupported. Since the schema covers them, the description is not fully complete, but it is not severely deficient.

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 enriches the parameters with concrete examples—e.g., items:["5.02"] = officer change, topic:"fed", series_id:"UNRATE"—and explains delivery channel constraints (email/sms) beyond the schema. However, it omits two enum types (patent_grant, clinical_trial) which the schema documents, leaving some semantics incomplete.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' This clearly distinguishes the tool from siblings like list_subscriptions, unsubscribe, and recent_alerts. The inclusion of supported types and delivery channels further clarifies 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 conveys when the tool is appropriate—for creating proactive subscriptions—and includes important exclusions like 'anonymous + BYO cannot persist subscriptions.' It also mentions pulling via recent_alerts as an alternative for feed delivery, though it does not explicitly name alternative tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description adds extra context rather than being the sole source. It discloses that results are drawn from a 'live catalog of thousands of tools' and that each example includes the 'exact tool + argument shape' that answers it, which is useful behavioral detail beyond the annotations. No contradictions found.

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

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

The description is moderately long but each section earns its place: a list of natural-language query examples up front aids intent matching, the middle explains the output format, and the end provides usage guidance. It is not excessively verbose and is well-structured despite being a single paragraph.

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 no output schema, the description sufficiently explains what is returned (category-bucketed example questions with tool+argument shape) and how to call it. It covers the default behavior and the optional parameter, making it fully self-contained for an agent to decide whether and how to invoke it.

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

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

Schema coverage is 100% for the single 'topic' parameter, providing baseline 3. The description adds semantic value by giving concrete examples ('finance', 'pharma', 'betting') and clarifying that omitting the parameter yields a 'cross-category spread.' This enriches the schema's list of possible values.

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

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

The description clearly states the tool's purpose: 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It specifies the exact output (category-bucketed example questions with tool + argument shape) and distinguishes itself from siblings by positioning itself as the FIRST tool to use when unfamiliar with Pipeworx's capabilities.

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

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

The description provides clear when-to-use context: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains usage variations (no args for full spread, topic parameter for focus). However, it does not explicitly state when NOT to use this tool or name direct alternatives, falling short of a full exclusionary guide.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds meaningful behavioral detail beyond these: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts' and 'Ownership is enforced.' These traits explain the soft-delete behavior and access restrictions, which are not disclosed by the annotations alone.

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

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

The description is three short sentences, front-loaded with the core action ('Cancel a subscription by id'), followed by essential constraints (ownership and deactivation). Every sentence contributes unique information without redundancy or filler. This is an exemplary model of concise, structured documentation.

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

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

For a simple single-parameter mutation tool with no output schema, the description covers all necessary angles: the action, the identifier provenance, ownership enforcement, and the soft-delete behavior with a pointer to recent_alerts. It answers likely agent questions about side effects and data persistence, making it fully self-contained for safe invocation.

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

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

The input schema covers 100% of the parameter semantics: the only required parameter 'id' is described as 'Subscription id (uuid) returned by subscribe.' The description only restates 'by id' without adding further meaning. Per the rubric, with high schema coverage the baseline is 3, and the description does not exceed that.

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

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

The description opens with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes from siblings like 'subscribe' and 'list_subscriptions' by stating the action is cancellation, and adds the nuance that the row is deactivated, not deleted, ensuring historical events remain available. This makes the tool's purpose unambiguous and differentiated.

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

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

The description provides clear context for use: it works by id and enforces ownership, so you can only cancel your own subscriptions. It implicitly guides when not to use (if you're not the owner) and points to 'recent_alerts' for historical events, but it does not explicitly mention alternatives like list_subscriptions or subscribe. Still, the guidance is clear enough for an agent to decide.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses internal routing (SEC EDGAR + XBRL fast path vs. grounded pipeline), return value structure (verdict, actual value, citation, reasoning), and the efficiency claim ('Replaces 4–6 sequential calls'). This adds valuable behavioral context not present in annotations.

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

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

The description is slightly longer than a one-liner but every sentence contributes: examples, use cases, routing details, and output. It is front-loaded with the most critical info (what the tool does) before diving into specifics. It earns a 4 because it is thoughtfully concise, though not as minimal as the two-sentence TDQS example.

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

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

Given no output schema, the description explicitly lists the return fields (verdict types, grounded or structured value, citation, reasoning). It also covers edge cases and routing logic. The tool is complex, but the description fully equips an agent to use and interpret results correctly.

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

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

Although schema coverage is 100%, the description enriches both parameters significantly. For 'claim', it gives realistic examples. For 'tolerance_pct', it explains the range, semantics (grading threshold), and use cases (hallucination detection), which is far more informative than the schema's default description.

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

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

The description opens with natural-language phrasings ('Is it true that…', 'fact check') and states the exact function: 'natural-language claim verification against authoritative sources.' It clearly distinguishes from sibling research tools by focusing on yes/no verdicts with evidence, making purpose unambiguous.

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

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

It provides explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing for company-financial claims vs. any other factual claim, which helps choose this tool appropriately. However, it does not explicitly name alternative sibling tools to avoid, so it earns a 4 rather than a 5.

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