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?

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior; the description adds useful meta-behavior: it auto-selects tools and returns stable citation URIs. This goes beyond the structured annotations without contradicting them.

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

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

The description is front-loaded and information-dense, but the 'START HERE' section is a run-on with apparent typos and repeats the tool name/role ('entry point, works on every tier, single call') instead of staying crisp. It earns a pass for dense routing guidance but is not as tight as it could be.

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

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

Given a single required schema parameter, rich annotations, and no output schema, the description covers the essential context: when to use, what it returns (structured answer + citations), and examples. It could briefly describe the answer shape or failure behavior, but nothing critical is missing for invoking the tool correctly.

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

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

Schema coverage is 100% and the single required question parameter is documented with aliases, so the description does not need to add much. The examples illustrate the expected natural-language format, but the description itself adds no parameter-specific semantics beyond what the schema already states.

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

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

States a specific, actionable function: routes a natural-language question to the right one of 5,767 tools across 1,506 verified sources and returns a structured answer with pipeworx:// citation URIs. It clearly differentiates from web search and from sibling tools like deep_research and ask_pipeworx_grounded by naming them explicitly.

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 strong when-to-use signals: prefer over web search for factual/current/historical data, plus trigger phrases and concrete examples. It also names exclusions: use ask_pipeworx_grounded for hallucination-resistant verbatim answers and deep_research for broad multi-part questions, and notes that breaking news is already routed internally.

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 that this is an experimental edge, that candidate routing changes may be live, and that the current state matches the stable router. It also explicitly states there is no fallback and that it is a fully working router. This is highly transparent about the tool's behavioral nature.

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

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

The description is well-structured and front-loaded with the beta identity and core purpose. Each sentence contributes useful context: identity, current candidate status, usage guidance, and operational guarantee. There is minor redundancy between 'same arguments, same response shape' and 'currently matches ask_pipeworx exactly,' but overall it is appropriately sized for the nuance it conveys.

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 fully explains what the tool does, when to use it, how it relates to the stable router, its current experimental state, and that it is a complete working router. It even covers the response shape by referencing ask_pipeworx. For a routing tool with no output schema, this is sufficient for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents the six parameters and their aliases. The description adds no parameter-specific meaning beyond noting that the tool uses the same arguments as ask_pipeworx. The baseline of 3 applies because the schema carries the parameter documentation burden.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,767 tools, arguments, and response shape. It states the experimental purpose: candidate routing improvements. This distinguishes it from the stable ask_pipeworx and ask_pipeworx_grounded siblings.

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

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

The description explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and clarifies that results are compared against the stable router. It also notes that no candidate is currently active, so behavior currently matches ask_pipeworx. This gives clear when-to-use guidance and references the relevant alternative.

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 substantial behavioral detail beyond the annotations: it returns verbatim evidence, confidence, source, fetched_at, and a refusal_reason when data doesn't directly answer, listing the specific refusal reasons. It also states the extraction uses ONLY the tool result, making the grounding behavior explicit. Nothing contradicts the readOnly/openWorld/idempotent hints.

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

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

The description is dense but every sentence earns its place: it defines the mode, explains the routing and extraction mechanism, enumerates the success and refusal return shapes, gives explicit usage guidance, and states the cost tradeoff. It is front-loaded with the most important identity signal and wastes no 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?

Since there is no output schema, the description compensates by fully specifying the return contract, including the exact refusal reasons. It also covers when to use the tool, how it differs from ask_pipeworx, and the performance tradeoff, making it operationally complete 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 description coverage is 100%, with the lone required parameter 'question' and its aliases fully documented. The description doesn't add parameter-level meaning, but the baseline of 3 applies because the schema already carries the semantic 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 clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific mechanism: same routing as ask_pipeworx, then extracting answers only from tool results. It also distinguishes itself from the sibling ask_pipeworx by its grounded, evidence-based behavior and explicit refusal path.

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

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

Usage guidance is explicit: use when answers will be quoted, cited, or acted on and when fact invention is unacceptable, while preferring ask_pipeworx for casual lookups. It even notes the cost tradeoff of one extra LLM call, giving the agent a clear decision rule between 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?

Annotations already declare readOnly/openWorld/idempotent, and the description goes well beyond them by disclosing account requirements, paid-dependency for 'thorough', latency expectations, parallel decomposition, gap reporting, citation fetchability, and contradiction detection. There is no contradiction with the annotations; the description adds substantial behavioral context.

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

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

The description is long but every sentence carries distinguishing information, and the account-required warning is front-loaded. The density is justified by the tool's complexity, though a little more structural separation would improve scannability.

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 carries the full burden of explaining return values; it does so by describing the findings packet, evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], and hop fields. It also covers auth, cost, latency, alternatives, and edge behavior for large records. This is remarkably complete for a complex research tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds meaningful depth-level behavior beyond the enum labels, explaining gap-recovery hops, lead-chasing, and contradictions for standard/thorough. It does not add much for 'question', but that parameter is self-explanatory.

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

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

The description names a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' delivered 'in ONE call.' It explicitly contrasts itself with open-web search and identifies its best use case: broad/multi-part structured-data questions. It is clearly distinguishable from sibling tools like ask_pipeworx.

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

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

The description gives explicit when-to-use guidance: use it for broad/multi-part structured research, and for single lookups use ask_pipeworx instead. It also names alternatives for breaking/current-news topics and warns that unsigned-in users should use ask_pipeworx. This is model-grade routing information.

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?

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds substantial behavioral context: it names all data sources, explains the return structure, clarifies that empty sections mean 'no data' not a bug, notes the USPTO API sunset and soft-fail, and mentions name resolution via SEC EDGAR. This goes well beyond the annotations, giving the agent a complete picture of what to expect.

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

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

The description is long but densely packed with necessary facts. It leads with examples and a directive, then systematically covers sources, return fields, and edge cases. It could be broken into bullets for easier scanning, but every sentence contributes value and nothing is verbose for its own sake.

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

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

Given the tool's complexity (multiple sources, no output schema), the description is exceptionally complete. It explains all expected outputs, the meaning of empty sections, resolution failures, and source fallbacks. An agent has everything needed to call it correctly and interpret results.

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

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

Schema coverage is 100% and both parameters are described. The description adds examples and clarifies that 'company' and 'ticker' are interchangeable and accept the same value shapes, and it explains the format of `value` (ticker, CIK, name). This is extra meaning beyond the schema, so it earns a 4.

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

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

The description clearly states it is a full cross-source profile of a US public company, with multiple query examples. It explicitly lists the sources and return fields, and it differentiates from siblings like deep_research and compare_entities. The purpose is unambiguous and specific.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack looksups when the user asks for a holistic view,' providing clear when-to-use guidance. It also distinguishes between public and private companies and mentions optional behavior for names vs tickers. Though it does not list explicit exclusions, the guidance is strong and actionable.

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 are all false, so the description carries the burden. It discloses rate limiting (5/day), that filing without an account returns a claim_token, and that the token can be reused later to read resolution status. It could be more explicit about whether feedback creates a persistent human-visible record, but the provided behavioral details are substantial.

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

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

Despite being long, every sentence earns its place: purpose, use cases, exclusion, formatting advice, token mechanics, team reading cadence, rate limit, and quota impact are all packed into one dense paragraph with no filler. It is front-loaded with the primary purpose.

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

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

Given the tool has no output schema and only false annotations, the description is remarkably complete: it covers what to report, what not to report, how to structure the message, the claim_token follow-up flow, and operational constraints. The nested context object is fully documented in the schema, and the description adds the missing usage 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?

The input schema already covers all parameters (100% coverage), so baseline is 3. The description adds meaningful semantics for claim_token by explaining the pwfb_… round-trip pattern and instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, which is beyond the schema.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates feedback types and explicitly distinguishes itself from other MCP-server tools by stating it is only for tools served by this Pipeworx connection.

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 concrete when-to-use guidance: bug, feature/data_gap, praise, and a clear when-not-to-use: tools from a different MCP server should be filed elsewhere. It also clarifies how to identify Pipeworx tools and what to avoid pasting.

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?

Beyond the read-only/idempotent annotations, the description discloses matching methodology, compatibility-code semantics, skipped/comparison counters, gross-vs-net fee treatment, and the meaning of null temporal alignment. This is unusually rich behavioral context that helps the agent interpret results correctly and avoid false signals.

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

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

The description is long, but it is densely structured with clear sections (modes, response, safety fields, skipped counters, fees, timing) and front-loads the core purpose. Every paragraph adds necessary operational detail given there is no output schema, so the length is mostly justified rather than padded.

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

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

With no output schema, the description must explain response semantics, and it does: top_spreads_pp, compatibility fields, per-entry flags, skipped counters, temporal_alignment, and the fee disclosure. An agent has enough information to call this tool and interpret its returned pairs, warnings, and limitations.

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

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

The schema already documents all three parameters at 100% coverage, and the description adds mode semantics: topic selects a pre-mapped macro shortcut, while the explicit params override the topic-mapped side. It also clarifies that both modes run the same token-overlap matcher, which goes beyond the schema's per-parameter descriptions.

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

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

The description immediately defines the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question, which is specific and distinct from single-venue or research tools. It names the core deliverable (spread in percentage points) and differentiates through the cross-venue, same-question scope even without naming siblings.

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

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

It clearly lays out two modes — pre-mapped topic shortcuts versus explicit event ticker/slug pairing — and explains when each is appropriate. It also gives practical cautions (most pre-mapped topics return compatibility_warning; pre-mapped does not mean tradeable), but it does not explicitly contrast this tool with closely related siblings like polymarket_arbitrage.

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

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

Annotations 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 annotations (readOnly, openWorld, idempotent), the description discloses important behaviors: it asserts nothing on ambiguous matches and returns `figi_candidates`, reports unresolved identifiers under `unresolved`, degrades gracefully when external sources are down, and replaces 2-3 manual lookups. This is rich contextual behavior that helps an agent predict outcomes.

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 actionable information. It is structured with clear sections (SUPPORTED TYPES, behavior details, degradation) and every sentence adds a distinct fact. The flow from purpose to usage to edge cases is logical and front-loaded, so length is justified.

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

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

For a complex tool with two parameters and no output schema, the description fully covers what an agent needs: input formats, accepted identifier types, resolution behavior for ambiguous/unresolvable names, fallback behavior, and internal cascade. It even hints at return values (`figi_candidates`, `unresolved`) without requiring an output schema.

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

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

The schema already covers both parameters well (enum for type, detailed description for value). The description adds extra meaning for `value`: clarifies to pass the entity name only, gives explicit examples, and explains edge cases like bond issuers vs trailing security-class words. That's value beyond the schema, so a 4 is warranted.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers like CIK, LEI, FIGI, RxCUI. It gives concrete query examples and differentiates itself from sibling tools by focusing on name-to-ID resolution. It also distinguishes between supported types (company vs drug), making its scope unambiguous.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID', providing a clear trigger condition. It also covers when NOT to use it (e.g., when a name does not identify a single instrument, it returns candidates) and describes graceful degradation for enrichment. This gives an agent decisive routing 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, 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety and side-effect behavior are covered. The description adds context about return content (entry counts, last sync time) but no additional behavioral traits such as auth requirements, rate limits, or failure modes. This is adequate but not rich.

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

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

Two sentences, no filler. The first sentence states the action and output; the second gives a concrete use case and enumerates the covered lists. Every clause earns its place.

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

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

For a zero-parameter read-only list tool with no output schema, the description conveys the essential return content (entry counts, freshness, list names) and the intended use case. Nothing critical is missing for an agent to invoke it correctly.

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

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

The tool has zero parameters and schema coverage is trivially 100%, so there is nothing for the description to clarify. The baseline for a no-parameter tool is 4, and the description appropriately focuses on output semantics instead.

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 and resource: 'List the US restricted-party lists this pack screens against' with concrete details about what is returned (entry counts, data freshness). It also lists the exact lists covered, distinguishing it from sibling tools like sanctions_screen and sanctions_entry.

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

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

The description provides a clear use case: 'Use to cite coverage in a compliance report' and enumerates the specific lists. It does not explicitly name sibling alternatives or state when not to use them, but it gives enough context for an agent to recognize this as the correct tool for coverage citation.

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 mark the tool as read-only, idempotent, and open-world. The description adds considerable behavioral detail beyond that: fuzzy matching with a 0-1 relevance score, matched aliases/programs/addresses/list attribution, empty matches array for clear names, Cyrillic romanisation into candidate sets with matched_form, and explicit refusal behavior (clear:null / screened:false) for non-romanised scripts. No contradiction with annotations.

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

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

The description is long but every sentence earns its place: core purpose, list scope, matching details, use cases, clear-result semantics, script handling, and refusal edge case. It is front-loaded with the main purpose and then gives operationally critical details. 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?

There is no output schema, so the description must carry the burden of explaining return values. It covers the key elements: empty matches array, relevance score, aliases, programs, addresses, list attribution, matched_form, and the clear:null / screened:false refusal case. It is sufficient for correct invocation, though a complete output shape or pagination isn't detailed.

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 every parameter is already documented in the input schema. The description adds context about matching behavior and output semantics, but not much extra for individual parameters. It also provides examples (Cyrillic, country, limit), which slightly enrich the param meaning. Baseline 3 holds.

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 ('Screen'), a resource ('person, company, vessel, or aircraft name against the US restricted-party lists'), and enumerates the exact lists covered. This clearly distinguishes it from sibling tools like sanctions_entry and sanctions_lists, which focus on individual entries and list metadata rather than screening a name across all lists.

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 the tool: 'Use for KYB / KYC / AML / export-control checks, and to check whether a supplier is subject to the forced-labor import ban before importing.' It also gives a key usage constraint: names in non-romanised scripts are refused, so users should pass the Latin transliteration. However, it does not explicitly name alternatives or exclusions, 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?

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?

Annotations already declare readOnly/openWorld/idempotent, and the description adds critical behavioral nuances: the meaning of each verdict, especially the crucial warning that 'could_not_verify' means the check did not happen and must not be treated as evidence. It also discloses the SEC fast path vs grounded pipeline behavior and the presence of verification_error{stage,detail}, going well beyond annotation data.

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

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

A longer description but well-structured and front-loaded with trigger phrases and the primary use case. Every sentence contributes: the routing logic, return format, and the critical error-handling caveat. Not bloated, though it could be tightened; the 'Replaces 4–6 sequential calls' line is useful context for selection.

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

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

Given no output schema, the description fully specifies the return values (verdict enum, actual value with citation, reasoning) and explains the difference between 'could_not_verify' and 'unsupported'—essential for correct interpretation. The routing and tolerance behavior are also covered, making the description self-sufficient for an agent to invoke and use the tool correctly.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description enriches the tolerance_pct parameter by explaining it overrides claim-implicated tolerance and recommending 1–2 for hallucination detection, which is not in the schema. The claim parameter is further illustrated with examples, adding practical guidance beyond the schema description.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, with specific trigger phrases ('fact check', 'verify the claim that...'). It distinguishes between company-financial claims (via SEC EDGAR + XBRL) and other factual claims (grounded pipeline), and notes it replaces multiple sequential calls, making it distinct from general ask/research sibling tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and describes the two routing paths for claim types. It does not name specific sibling tools as alternatives, but the 'Replaces 4–6 sequential calls' gives context on when this is preferred over a multi-step pipeline. Minor gap: no explicit 'do not use when...' or contrast with general ask tools.

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