Scryfall

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds critical behavioral details: how probing works (per-model scores), the free default model, billing for Anthropic calls, and the return structure {score, confidence, signals, raw_response}+combined view. No contradictions.

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

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

The description is three sentences with no fluff. It front-loads the core purpose, then addresses parameters and use cases. Every sentence serves a 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 4 parameters and no output schema, the description explains output format and parameter usage well. Lacks mention of rate limits or error scenarios, but for a read-only, idempotent tool this is minor.

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

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

Schema descriptions cover all 4 parameters (100% coverage). The description adds usage context: explains that models defaults to workers-ai, _apiKey is needed for Anthropic, and context disambiguates entities. This adds value beyond the schema definitions.

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

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

The description clearly states the tool probes LLMs for visibility of a business/brand/product/topic, returns a score (0-100), and distinguishes from siblings by specifying default model and BYO key option. The verb 'probe' and resource 'LLM visibility' are 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 provides explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to use the _apiKey param. However, it does not explicitly say when not to use or point to alternative tools for different purposes.

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 carry the safety profile (readOnlyHint, openWorldHint, idempotentHint all true, destructiveHint false), so the bar is lower. The description adds genuine behavioral context: the question is routed to one of 5,710 tools across 1,494 verified sources, arguments are filled automatically, and answers come with stable pipeworx:// citation URIs. Minor gap remains around failure behavior or out-of-scope queries, but 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?

Dense but every sentence earns its place: precedence rule, domain list, routing behavior, trigger phrases, examples, and exclusion routing. Slightly long and the final sentence is a run-on with slash-separated alternatives, but the verbosity is justified for a tool that routes to 5,710 sub-tools.

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 one-parameter interface, the description fully covers what the tool does, when to prefer it, what it returns (structured answer with pipeworx:// citation URIs), and when to use alternatives. With no output schema, the description partially fills the return-value gap. Minor omissions: no mention of latency/cost expectations for a mega-router.

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% (question plus five documented aliases), so the baseline is 3. The description adds value above that by modeling the parameter: trigger phrases and six realistic example questions ('current US unemployment rate', 'Apple's latest 10-K') teach an agent what a well-formed input looks like in practice.

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 precise job: answering factual questions about real-world entities, events, and numbers with authoritative, cited structured data. The domain list (SEC, FDA, FRED/BLS, USPTO, ATTOM, clinical trials, etc.) makes the resource unmistakable, and naming siblings like deep_research and ask_pipeworx_grounded differentiates it from alternatives.

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?

Opens with 'PREFER OVER WEB SEARCH', enumerates trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), gives six concrete example queries, and closes with explicit exclusions routing claims verification to search_cards/ask_pipeworx_grounded, multi-part research to deep_research, and breaking news to news-feeds packs. The when/when-not decision is fully specified.

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 the live experimental state: candidate improvements are enabled only when under test, none is active right now, and it currently matches ask_pipeworx exactly. The clarification 'Falls back to nothing — this IS a full working router' also prevents a misinterpretation that this is a stub.

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 reasonably concise given the amount of live-state information it conveys. It front-loads the core identity and then gives usage, current state, and a useful non-stub clarification. A little redundancy exists around 'matches ask_pipeworx exactly,' but the details earn their 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 beta router with mutable behavior, the description provides the essential context: what this tool is, how to use it, what is currently active, and how it relates to the stable router. Since no output schema exists, describing the same response shape as ask_pipeworx is helpful, though it assumes the agent already knows ask_pipeworx's behavior.

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

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

Schema description coverage is 100%, and the schema already documents question plus all aliases. The description only says 'same arguments' as ask_pipeworx and adds no additional meaning about parameter formats, defaults, or constraints.

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 by identifying this as 'Beta version of ask_pipeworx' and explicitly calls it an 'identical universal router' with the same tool set and response shape. It clearly differentiates the beta variant from the stable sibling by describing candidate routing improvements and the experimental edge.

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

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

It gives an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains how results feed into comparison against the stable router. It does not explicitly state 'do not use this when you need stable/confirmed behavior,' though the beta/stable contrast strongly implies it.

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

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

Annotations already establish read-only, open-world, idempotent, non-destructive behavior, and the description adds meaningful behavioral context beyond those: it only answers from the tool result, returns a structured success payload with evidence, and explicitly enumerates refusal reasons like not_in_source and data_truncated. This gives the agent a reliable mental model of when the tool will refuse rather than guess.

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: it front-loads the core value proposition, then covers output shape, refusal behavior, usage conditions, and cost trade-off, all without repetition. The structure moves from what it does, to what it returns, to when to use it, which is an ideal ordering for an agent scanning for invocation criteria.

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

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

Despite having no output schema, the description fully documents the success and failure return envelopes, including field names and refusal reason enum values. It also supplies the key decision factor (extra LLM call vs ask_pipeworx) and the use cases where grounded mode matters. Nothing critical is missing for correct selection and invocation.

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

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

Schema description coverage is 100% and the single required parameter 'question' is already described in the schema, so the description does not need to replicate parameter details. Baseline 3 applies because the description adds no new parameter-level meaning, but the schema fully carries that 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 opens with a precise phrase, 'Hallucination-resistant answer mode for high-stakes reads,' and explains exactly what the tool does: routes to the right source, fetches data, then extracts an answer using only the tool result. It also distinguishes itself from the sibling ask_pipeworx by emphasizing the grounded-extraction behavior and refusal states, 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?

Explicit 'when to use' guidance is provided: whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts, with examples such as financial verdicts and legal claims. It also explicitly says to prefer the sibling ask_pipeworx for casual lookups due to the extra LLM call cost, which is clear 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?

Beyond the annotations (readOnlyHint, etc.), the description details numerous behavioral traits: low-confidence resolution short-circuits, closed market handling, wide-spread warnings, cancellation rule parsing, and blocking paths. This provides extensive transparency about what the tool does and its edge cases.

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

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

The description is long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded with the main purpose and usage. While not minimal, every section adds value and aids understanding, so it earns a 4.

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

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

Given the complexity of the tool (multiple classifiers, fan-out logic, resolver contract, cancellation rules) and the absence of an output schema, the description is remarkably thorough. It covers edge cases, safety mechanisms, and response shapes, enabling correct agent invocation.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description does not add new semantic meaning beyond what the schema provides (e.g., market parameter types, depth options, include_raw). Baseline 3 is appropriate as the schema already handles parameter documentation.

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: research a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and use cases ('should I bet on X', etc.). The tool is distinct from siblings like polymarket_edges or deep_research, and the description makes its unique function clear.

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

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

The description explicitly lists when to use the tool (e.g., 'should I bet on X') and provides examples for various bet types. However, it does not explicitly state when NOT to use it or name alternative tools for different scenarios, which would improve guidance.

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

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

Annotations already declare readOnly, non-destructive. Description adds off-calendar handling and data sources (SEC EDGAR/XBRL, FAERS, FDA). Slightly more detail could enhance transparency.

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

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

Single paragraph with front-loaded examples. Efficient but could be broken into shorter sentences for readability.

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

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

No output schema, but description explains returned data: paired data + citation URIs, sorted by primary metric. Sufficient for agent expectations.

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 description adds context by explaining what each type returns and how values should be formatted, e.g., tickers for company, drug names for drug.

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

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

The description uses specific verbs and resources: 'side-by-side comparison of 2–5 companies or drugs in one parallel call.' It clearly distinguishes from sequential lookups and lists example queries.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides concrete example phrases for users.

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

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

Annotations already cover read-only/idempotent safety, but the description adds substantial behavioral context: account and plan requirements, decomposition into parallel tool calls, gaps[] never invented, hop field, citation_uri fetchability, contradictions[] for standard/thorough, semantic excerpting, and expected latency. No contradiction with the annotations exists.

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

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

The description is long but front-loaded: the account requirement and sibling routing come first, followed by core behavior, then depth-mode nuances and latency. Some redundancy around depth modes exists (schema also explains them), but every sentence either adds operational guidance or return-format detail, so length is mostly earned.

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 adequately fills the gap by specifying the findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], hop/citation_uri fields, and expected timing. It also covers authentication, plan tier, and when to choose a sibling tool, making the definition complete for an agent deciding 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%, so the schema already documents both parameters. The description still adds useful semantics beyond the schema by explaining paid-thorough access, the difference between standard and thorough gap recovery, and why the question parameter should be broad/multi-part. This clears the baseline for fully-documented schema parameters.

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: 'Grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources' in ONE call. It also explicitly distinguishes itself from open-web search and names ask_pipeworx as the single-lookup alternative, so an agent can tell deep_research apart from 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?

Explicit when-to-use guidance is present: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' It also names its best-fit scenario ('broad/multi-part questions over structured data') and the paid-tier constraint for depth:thorough.

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. The description adds valuable behavioral details: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations to explain the exact output and usage convenience.

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 relatively concise given the amount of information it conveys, starting with the core purpose and then listing domains. It's slightly lengthy but every sentence serves a purpose. A minor improvement could be more structured bullet points, but it's already effective.

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

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

Given the tool's complexity (6 parameters, no output schema), the description fully covers what the tool returns (top-N tools with full schemas and examples) and when to use it (discovery phase). It provides enough context for the agent to understand the tool's utility and output format.

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

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

Schema description coverage is 100% with detailed parameter descriptions. The description further clarifies the aliasing of query parameters ('Accepts task, q, description, search as aliases') and provides concrete examples of natural language queries. This adds significant meaning beyond the schema alone.

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

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

The description clearly states 'Find tools by describing the data or task' with a specific verb and resource. It distinguishes itself from siblings by being the discovery tool, with an extensive list of domains it covers (SEC filings, FDA drugs, etc.). This leaves no ambiguity about the tool's purpose.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use the tool and implies that for specific tasks with a known tool, other tools should be used instead.

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 (read-only, open-world, idempotent), the description discloses cross-source fan-out, soft-fail for patents, data sorting, and URI generation. 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 thorough but slightly verbose. Front-loaded with example queries and purpose, then details. Could be more concise, but effectively structured.

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

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

Given the complexity of aggregating multiple sources, the description comprehensively covers return fields, limitations (patents sunset), and prerequisites. Output schema is absent, but description suffices.

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 clear descriptions. The description adds usage examples (ticker vs CIK) and reiterates restrictions, adding slight value above the schema.

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

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

The description clearly states the tool's purpose: providing a full cross-source profile of a US public company in one call. It specifies the verb (profile), the resource (US public company), and distinguishes from sibling tools like resolve_entity.

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

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

Explicitly states when to use ('ALWAYS PREFER over chaining...') and when not to use ('Names not supported — use resolve_entity first'). Provides clear alternatives and context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds no new behavioral traits beyond stating deletion, which aligns 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?

Two sentences, no fluff. Front-loaded with action and resource, then usage 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?

Simple tool with one param and no output schema. Description covers purpose, usage, and pairing. Annotations cover safety. Complete.

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

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

Schema has 100% coverage with description 'Memory key to delete'. Description adds no additional meaning beyond what schema already provides.

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

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

Description uses specific verb 'Delete' and resource 'memory by key'. Clearly distinguishes from siblings '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?

Explicitly states when to use: context stale, task done, clear sensitive data. Also mentions pairing with remember and recall for alternatives.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It clarifies the non-destructive nature and output format, though it stops short of discussing potential limitations like rate limits or page fetch failures.

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

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

The description is concise with a clear front-loaded purpose sentence, followed by a brief elaboration and bullet-like use cases. Every sentence adds value, though the list of crawlers could be slightly trimmed without loss.

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

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

Given the tool's simplicity (2 params, no output schema), the description adequately covers purpose, usage, and behavior. It mentions the output format ('single text blob') and standard markdown, which is sufficient for an agent to understand the result.

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% and includes default/max for max_links. The description repeats this information without adding new semantic meaning, so it meets the baseline but does not exceed it.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL'. It specifies the verb (generate) and resource (llms.txt), and by listing specific AI crawlers and the output format, it distinguishes itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It implies when to use but does not explicitly state when not to use or name alternatives, which is acceptable given the context.

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

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

Annotations already declare the tool as read-only, idempotent, and safe (readOnlyHint, destructiveHint). The description adds valuable context: fuzzy matching behavior and the specific details returned (mana cost, oracle text, etc.). No contradictions.

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

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

A single, well-structured sentence that front-loads the core action and includes necessary details. No unnecessary words.

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

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

Given the lack of output schema, the description appropriately outlines the return content (full card details including various attributes). It does not discuss error handling or rate limits, but the annotations cover safety. The tool's purpose is sufficiently complete for an MTG card lookup.

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 includes descriptions for both parameters. The description adds 'fuzzy matching' which is not in the schema, clarifying how the name parameter behaves. This adds value beyond the schema.

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

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

The description clearly specifies the action ('look up'), the resource ('single MTG card'), and the method ('by name, fuzzy matching'). It distinguishes itself from sibling tools like 'search_cards' (multiple results) and 'random_card' (random).

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 states usage ('look up a single card by name') but does not provide explicit guidance on when to use this versus alternatives like 'search_cards' for broader queries or 'random_card' for random picks. Context from sibling names implies the distinction but is not stated.

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 well-covered. The description adds that the tool returns all sets with specific fields, which is useful but does not elaborate on other behavioral aspects like pagination or dynamic data. Given the annotations, the description provides adequate but not exceptional transparency.

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

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

The description is a single, concise sentence (18 words) that front-loads the verb and resource. Every word provides necessary context, and there is 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 the tool's simplicity (no parameters, no output schema), the description fully covers what the tool does and what it returns. It lists the exact fields returned, which compensates for the lack of an output schema. The tool is a straightforward list, so no additional context is needed.

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 the input schema is empty with 100% coverage. The description correctly implies no inputs are needed, so it adds no unnecessary information. This is ideal for a parameterless tool.

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 verb 'List' and specifies the resource 'Magic: The Gathering (MTG) sets/expansions', clearly indicating the tool's purpose. It also enumerates the exact fields returned (codes, names, types, release dates, card counts), which distinguishes it from sibling tools that deal with cards (e.g., search_cards, get_card).

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

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

The description clearly implies that the tool should be used when a complete list of MTG sets with their metadata is needed. While it doesn't explicitly mention when not to use it or provide alternatives, no sibling tool performs a similar function (listing sets), so the guidance is clear enough for an agent to choose correctly.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the default list is active subscriptions only, and confirms the returned fields. This adds context beyond annotations but is not extensive.

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 precise sentences: first states purpose and output, second provides usage guidance. No extraneous text.

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

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

Given the simple parameter set and no output schema, the description adequately covers the tool's behavior, return fields, and usage context. Complete for a list operation.

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

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

The schema covers the single parameter at 100% coverage. The description's mention of 'active subscriptions' reinforces the default behavior, adding marginal meaning 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 lists the caller's active subscriptions and enumerates the return fields (id, type, etc.), distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly advises using this tool to review monitoring before adding more subscriptions or to find an id to cancel, providing clear when-to-use guidance.

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

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

Annotations are minimal (all hints false), so the description carries the full burden of behavioral disclosure. It reveals rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token flow ('Filing without an account returns a `claim_token`; pass it back later ... to read whether it was fixed'), and operational context ('The team reads digests daily and signal directly affects roadmap'). This is thorough and adds significant value beyond the annotations.

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

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

The description is a single dense paragraph covering all necessary facets: purpose, boundaries, token flow, rate limits, and cost. Every sentence is purposeful and none are filler, but the wall-of-text format could be more scannable with bullet points or short paragraphs. It is appropriately sized for the tool's complexity, so the slight lack of structure is the only limiting factor.

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

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

With no output schema, the description compensates fully by explaining what the tool returns (a claim_token), how to use that token, what constraints exist (rate limit, free, no quota), and what the team does with feedback (reads digests daily). It also clarifies the exact domain ('Pipeworx connection') to avoid misreporting. This is complete for an agent to invoke the tool without ambiguity.

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

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

Schema coverage is 100%, with descriptions for every parameter, so baseline is 3. The description adds cross-parameter workflow guidance: how to use claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), that message should not include the end-user's prompt, and message length expectations ('1-2 sentences typical, 2000 chars max'). This meaningfully enriches the schema descriptions, though it doesn't detail every enum value (the schema already does 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 immediately states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback types (bug, feature, data_gap, praise) and distinguishes itself from non-Pipeworx MCP tools by explicitly stating 'ONLY for tools served by this Pipeworx connection.' This is a specific verb+resource that clearly differentiates it from the 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?

The description gives explicit when-to-use criteria: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'if the tool came from a different MCP server ... file it with that server instead.' Additionally, it explains the claim_token follow-up workflow, giving an agent complete usage guidance.

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

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

The description adds significant behavioral context beyond annotations: the data source (CF analytics-engine), lack of PII, and caching behavior (5min-1h depending on window). This fully discloses the tool's operational characteristics.

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

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

The description is concise: two sentences of purpose followed by bullet points. Every sentence adds value, and the key information is front-loaded. No unnecessary words.

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

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

Given the simplicity of the tool (1 optional enum parameter, no output schema), the description is complete: it explains what is returned, the data source, caching, and use cases. No gaps remain.

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

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

With 100% schema coverage and a clear enum description, the description adds extra semantics by explaining the effect of window choice: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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 returns top tools, top packs, and total call volume over a recent window. It distinguishes itself from siblings by focusing on aggregated usage trends from other AI agents, not specific tool details.

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

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

Three explicit use cases are provided, and window selection guidance is given. However, it does not explicitly state when not to use this tool or mention alternatives like discover_tools for specific tool details.

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, not destructive), the description reveals key behaviors: internal logic (Jaccard similarity threshold, partition filter, fill check), response structure, and trade signals. It explains when signals are actionable and warns against trading when realizable edge is non-positive.

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 overall purpose, then details modes and internal logic. However, it is somewhat lengthy due to technical details; a slightly more concise version could maintain clarity while reducing verbosity.

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

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

Given the tool's complexity and lack of output schema, the description provides thorough coverage: return fields, fill check conditions, edge cases (low similarity, placeholder filtering), and trade recommendations. It leaves no critical gap for an agent to understand how to use this tool effectively.

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

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

Although the schema covers both parameters (100% coverage), the description adds rich meaning: examples of event slugs and topic queries, explanation of internal processing (Jaccard similarity, partition filter), and the fill check procedure. This far exceeds what the schema provides.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the verb (Find), resource (arbitrage opportunities), and method. The purpose is distinct from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: no args for trending_scan, event for specific market, topic for cross-event scan. It recommends event mode and points to an alternative tool (polymarket_fill_risk) for custom sizing. It also explains the differences between modes.

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 extensive behavioral details beyond annotations: caching, response structure (by_segment, diagnostics), model families, slippage, Kelly fractions, 24h-move warning, and Fed bet exclusion. 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 long but well-structured with headings (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). It is front-loaded with the main purpose. Some verbosity 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?

Given 9 parameters, no output schema, and nested response, the description comprehensively explains segments, response top-level, diagnostics, and why Fed bets are excluded. It fully equips an agent to use the tool correctly.

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

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

Since schema coverage is 100%, baseline is 3. The description adds value by explaining the rationale behind parameters (e.g., min_partition_leg_kelly for partition arbs) and how they interplay, elevating it above just schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx data disagreement.

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 (discovering opportunities without paging markets) and explains tradeable-edge knobs but does not explicitly mention when not to use or compare with alternatives like polymarket_arbitrage. Still, the context is strong.

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

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

Annotations already declare safe read-only behavior. Description adds rich behavioral details: response structure (tracked, expired, snapshot_dates), time-series handling, decay computation, and limits (60-day TTL, gaps). No contradictions.

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

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

Information-dense but slightly verbose. Well-structured with sections (args, response, limits). Some repetition could be trimmed.

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

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

No output schema, but description fully explains return format (tracked, expired, snapshot_dates) and covers limits and edge cases. Complete for the tool's complexity.

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

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

Schema coverage is 100%; description adds default values, clamp range for 'days', and explicit options for 'window' (24hr, 1wk, 1mo), providing meaning beyond schema.

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

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

Clearly states it provides 'edge persistence and decay telemetry' from daily snapshots. Distinguishes itself from sibling 'polymarket_edges' by focusing on historical persistence rather than 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?

Explicitly answers when to use: 'how long has this edge existed and is it shrinking?' Implies not for current edges (use polymarket_edges). Could name alternatives more directly.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral context: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, and verdict. It warns about thin books and the danger of partial basket fills. 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 well-structured with clear sections for single-market and basket modes, uses bullet points in the input schema, and front-loads the core purpose. While thorough, it is slightly lengthy but every sentence adds necessary detail.

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

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

Given 4 parameters, no output schema, and sibling tools like polymarket_arbitrage and polymarket_edges, the description sufficiently explains inputs, outputs, and risks. It lists many output fields (top_of_book, vwap_fill_price, etc.) though not in a structured schema format. It is comprehensive enough for an agent to use correctly.

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

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

Schema description coverage is 100%, but the description adds value by explaining the default side logic for basket mode ('auto from partition sum') and clarifying size_usd for basket as 'settlement notional S (shares per leg; each share pays $1)'. This enriches understanding beyond the schema.

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

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

The description states a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, and the purpose is unique among siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why by noting the risk of partial fills converting arb into unhedged directional positions. Also specifies required parameters (one of `market` or `event`).

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

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

The description goes well beyond the readOnly/idempotent annotations by detailing compatibility_warning, compatibility_codes, skipped cross-type/subtype counters, temporal_alignment, and the rule that unknown legs are never paired. This richly prepares the agent for edge cases and response semantics. 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 dense, front-loading the core purpose and then systematically covering modes, response structure, safety fields, and caveats. Some repetition of the topic list already present in the schema exists, but given the complexity and absence of an output schema, most sentences earn their place.

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

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

With no output schema, the description compensates thoroughly by specifying the response shape, each safety field, the meaning of compatibility codes, skipped counters, and temporal alignment. An agent has sufficient information to call the tool correctly and interpret even edge-case results.

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

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

The schema already documents all three parameters at 100% coverage, establishing a baseline of 3. The description adds value by explaining that topic shortcuts auto-fetch matching events on each venue and that explicit ticker/slug override the mapped side, which clarifies mode interaction beyond the schema.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, naming a specific resource and function. It is distinct from the Polymarket-only siblings by virtue of the Kalshi comparison, but it never explicitly names or contrasts a sibling tool, so differentiation is implied rather than 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?

The two modes (topic shortcuts vs explicit ticker/slug) are clearly explained, including when each mode is appropriate, and the caveat that 'pre-mapped ≠ tradeable' provides practical guidance. However, it does not explicitly name alternative tools or state when this tool should not be used.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds value by explaining the filtering capability and Scryfall query syntax, but does not disclose additional behavioral traits beyond annotations.

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

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

The description is a single concise sentence with no wasted words. Essential information is front-loaded: what the tool does and how to filter. Perfectly structured for quick parsing.

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 only one optional parameter and no output schema, the description sufficiently covers the tool's purpose and filtering. It could optionally describe the return format but is still complete for a simple random retrieval tool.

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

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

The single parameter 'query' is described in the schema with 100% coverage. The description goes beyond by providing concrete examples ('is:commander', 'c:blue'), which clarifies the query format and adds meaning.

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 retrieves a random MTG card with optional Scryfall query filtering. The verb 'get' and resource 'random card' are specific, and it distinguishes from sibling tools like get_card (specific card) and search_cards (list).

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 example filter queries but does not explicitly state when to use this tool versus alternatives like search_cards. Usage is implied through context but lacks explicit guidance or exclusions.

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

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

Annotations already cover readOnly, idempotent, destructive hints. Description adds context about scoping and pairing with remember/forget, but does not contradict annotations.

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

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

Two sentences, front-loaded with core action, 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?

Completely covers usage, behavior, and relationships for a simple 1-param tool with no output schema.

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

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

Schema coverage is 100%. Description clarifies that omitting key lists all keys, adding meaning beyond schema.

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

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

States it retrieves a value saved via remember or lists all keys if key is omitted. Clearly distinguishes from siblings (remember, 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?

Provides concrete use cases (target ticker, address, research notes) and scoping context. Lacks explicit when-not-to-use but implicit through examples.

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, openWorldHint, idempotentHint, destructiveHint=false. The description adds value by explaining the mark_read parameter's effect on read state and that polling is safe. 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 a single paragraph of ~5 sentences, front-loaded with the core purpose, then detailing parameters and alternative access. Every sentence adds value 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 all described in schema, and no output schema, the description provides sufficient context by listing what each event carries (source, citation_uri, raw payload). It also mentions the direct endpoint for alternative use. Could be slightly more complete by noting default ordering or pagination, but it's adequate.

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

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

Schema coverage is 100% (all 5 parameters have descriptions). The description enhances each parameter: gives an example for 'type' (sec_8k), specifies ISO timestamp for 'since', explains the effect of 'mark_read' and 'unread_only', and mentions 'limit' implicitly through the default. This adds meaning beyond the schema.

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

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

The description starts with 'Pull fired events from your subscription feed' — a clear verb+resource statement. It specifies what each event carries (source, citation_uri, raw payload) and lists filtering options. This distinguishes it from sibling tools like list_subscriptions or subscribe which manage subscriptions rather than retrieve events.

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

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

The description explains when to use this tool ('Polls work fine') and the alternative direct endpoint ('the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards'). It describes filtering options but doesn't explicitly state when not to use it or compare to specific 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?

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral detail: multi-source fan-out (SEC EDGAR, GDELT→GNews, USPTO), fallback mechanism, parameter shorthand support, and return structure (changes[] grouped by source + URI citations).

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

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

The description is a single paragraph that front-loads example queries. It is informative without being verbose, but could benefit from structured sections for parameters or data sources. Every sentence contributes meaning.

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

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

Given the tool's complexity (multiple sources, fallback, parameter options, no output schema), the description covers essential behavior, parameter details, return structure, and sibling differentiation. It leaves no critical gaps for agent invocation.

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

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

Schema coverage is 100%, but the description adds value by explaining accepted formats for 'since' (ISO date and relative shorthand with examples), the fact that 'value' accepts ticker or CIK, and a usage recommendation for 'since' (typical monitoring: '30d' or '1m').

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

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

The description clearly states the tool provides a change feed for a company over a recent time window, with specific example queries. It explicitly distinguishes from sibling tool entity_profile by contrasting 'change feed' vs '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?

The description provides explicit usage contexts ('What's new with X' queries) and guidance on when to use entity_profile instead. It also explains internal fallback logic between GDELT and GNews, and notes a soft fail for USPTO.

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 significant value beyond annotations: it clarifies scoping by identifier, persistence behavior for authenticated vs anonymous sessions (24 hours), and that it stores key-value pairs. Annotations indicate idempotentHint=true and destructiveHint=false, which align with the description. No contradictions.

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

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

The description is very concise with no wasted words. The first sentence states the core purpose, followed by usage guidance, scope, and pairing info. Every sentence adds value.

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

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

Given the tool has only two simple parameters and no output schema, the description is fully sufficient. It covers purpose, usage, scope, persistence, and related tools (recall, forget). No gaps.

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

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

Schema coverage is 100% with descriptions for key and value. The description adds specific examples of key names (subject_property, target_ticker) and states value can be any text, supplementing the schema's generic descriptions.

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

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

The description clearly states the tool saves data for reuse across conversations and sessions, with specific examples like resolved ticker, target address, user preference. It distinguishes from sibling tools (recall, forget) by explicitly pairing with them.

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

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

The description explains when to use the tool ('when you discover something worth carrying forward') and implies when not to (temporary data). It mentions pairing with recall and forget but does not explicitly exclude alternative tools like list_sets or generate_llms_txt.

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 readOnlyHint/idempotentHint annotations, the description adds that unresolved identifiers are returned under `unresolved` rather than omitted, and that LEI/FIGI enrichment degrades gracefully if upstream services are unavailable. This provides valuable behavioral context for failure modes.

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

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

The description is front-loaded with the core purpose and query examples, but it's quite verbose with many parentheticals and nested details. The 'SUPPORTED TYPES' label helps structure, but trimming would improve readability.

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

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

With no output schema, the description carries the burden of explaining return values, which it does by naming fields (CIK, ticker, LEI, FIGI, RxCUI, etc.) and the `unresolved` field. It also covers input flexibility, source attribution, and failure behavior, making it comprehensive for the tool's complexity.

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

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

The schema already documents `type` (enum) and `value` with examples. The description adds meaning by noting that company input can also be an ISIN, and explains the resolution pipeline for both company and drug, enriching the semantic understanding of valid inputs.

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 first sentence explicitly states the tool resolves user-spoken names to canonical/official identifiers, with examples like 'ticker' and 'CIK'. It also says 'Use FIRST' and specifies two supported types, clearly differentiating it from sibling tools like entity_profile.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that a call replaces 2–3 manual lookups, but it doesn't explicitly mention when not to use it or name alternative tools for other use cases.

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 significant behavioral context beyond the annotations: it probes each entity with 'ai_visibility_check', ranks by score, and returns a ranked list with specific fields. It also mentions the first entity is treated as the 'subject' for narrative. However, it does not disclose potential costs (e.g., Anthropic API key usage) or rate limits beyond what's in the schema. 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 efficiently structured: first sentence states the primary action, second sentence explains the method and output, third sentence provides the use case with an example. No wasted words; all content is relevant 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 the tool has 4 parameters, 1 required, no output schema, and moderate complexity, the description covers the return format (ranked list with score, confidence, signal density), the process (probing via ai_visibility_check), and the use case. It does not explain error handling or edge cases (e.g., what if an entity fails?), but the annotations (readOnly, idempotent) and schema fill some gaps. Adequate for an informational tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that the first entity in 'entities' is treated as the 'subject' for narrative and the rest as competitors. It also contextualizes the model selection and API key. This extra semantic clarity justifies a 4.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side. It specifies a specific verb ('Compare'), resource ('AI visibility'), and scope ('multiple entities'). It distinguishes itself 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?

The description provides a clear use case: 'competitive AI-marketing audits' and an example question. While it doesn't explicitly state when not to use it or list alternatives, the sibling tool names suggest 'ai_visibility_check' for single entities, and the context implies this is for multi-entity comparisons. A more explicit exclusion would elevate the score.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint as false. The description adds value by detailing the composite nature, graceful degradation on partial failures, and the potential 5-30 second first measurement for bundlephobia. No contradictions.

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

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

The description is relatively long but well-structured, with the core purpose and use case front-loaded. Every sentence provides useful information, though slight trimming could improve conciseness without losing value.

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

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

Given the tool has only 2 parameters (both documented), no output schema, and rich annotations, the description covers all essential aspects: composite behavior, return structure (summary block, advisories, alternatives), limitations (NPM only, timeouts), and error handling (sources_failed). It is sufficiently complete for an AI agent to understand and invoke the tool correctly.

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

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

Schema description coverage is 100%, but the description adds extra meaning: it clarifies that scoped packages (e.g., '@types/node') are accepted for the 'package' parameter and that 'version' defaults to the latest. This goes beyond the schema's basic descriptions.

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

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

The description clearly defines the tool as a composite check for npm packages, combining deps.dev and bundlephobia data. It specifies the exact use case ('should I add this npm package to my project') and distinguishes from siblings by stating 'NPM ecosystem only in v1' and directing other ecosystems to an alternative tool.

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

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

The description provides explicit guidance on when to use the tool ('is X safe / popular / small', 'what does adding lodash cost me'), mentions partial failures and timeouts, and notes alternatives for other ecosystems. It could improve by explicitly stating when not to use it, but the guidance is already effective.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds value by specifying return fields (names, types, oracle text, etc.) and using external syntax (Scryfall). No contradictions. Still lacks pagination details, but acceptable.

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

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

Two concise sentences, front-loaded with purpose, then examples. No unnecessary words, highly efficient.

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

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

Despite no output schema, description fully explains return values (names, types, oracle text, sets, rarities, prices). With examples and parameter guidance, it's complete for a search tool.

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

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

Schema coverage is 100% so baseline 3. Description adds concrete examples for query, order, and unique, which help understanding beyond schema descriptions.

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

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

Description explicitly states the tool searches MTG cards using Scryfall query syntax, with examples. It clearly distinguishes from siblings like get_card (single card) and list_sets (sets).

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

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

Description gives clear query syntax examples and explains what is returned, but does not explicitly state when to use vs. alternatives like get_card or random_card. However, context from sibling names makes it fairly 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, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation and flagging, and return of character offsets and similarity scores.

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-organized: starts with the core purpose, then usage context, then return details, then pairing with other tools, and finally technical specifics. It is informative but could be slightly more concise without losing clarity.

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

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

Given no output schema, the description effectively explains return values (top-N passages with offsets and similarity scores). It also covers pairing with another tool and technical details about the embedding model and limits. Still, it could mention error conditions or edge cases (e.g., empty result handling).

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that 'text' is 'the document text you already pulled', 'query' is a natural-language question with examples, and clarifying the max length constraint for text. This goes beyond the schema's minimal descriptions.

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

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

The description clearly specifies 'semantic search INSIDE a fetched record' with a specific verb ('search') and resource ('inside a fetched record'). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and the gateway, and by contrasting with cramming the record into the prompt.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded. It provides clear context but does not list explicit when-not-to-use scenarios beyond the implied 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 significant behavioral context beyond annotations, such as the need for OAuth account, delivery channel constraints (SMS cap, phone verification), webhook HMAC signing, and auto-disable after 10 failures. 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 well-structured: it starts with the main purpose, then covers requirements, supported types with examples, and delivery channels. Every sentence adds value, no 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?

The description thoroughly covers input parameters and behavioral details, but lacks explicit specification of the return value structure beyond 'new subscription id'. Given the complexity and no output schema, slightly more detail would be beneficial.

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

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

With 100% schema coverage, the description adds substantial meaning with detailed examples for each subscription type and delivery channel constraints, clarifying what each parameter does beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose as creating a proactive monitoring subscription to a live-data event stream and returning a new subscription ID. It uses specific verbs ('Create') and resources ('subscription'), and is easily distinguished from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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 context for usage, including the requirement for a Pipeworx OAuth account and examples for each subscription type. However, it does not explicitly state when not to use this tool or directly contrast it with alternatives for one-time queries.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it returns example questions with tool calls and can be called with no arguments. No contradictions.

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

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

Description is front-loaded with alternative queries and clear structure. Slightly long but each sentence adds value; could be tightened slightly.

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 an onboarding tool, description covers purpose, when to use, parameters, and return content. No output schema needed; description explains what is returned adequately.

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

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

Schema covers 100% of parameters. Description adds meaning by explaining the optional topic parameter with examples and behavior when omitted, going beyond the schema's 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 returns category-bucketed example questions with exact tool calls. It distinguishes from siblings by being the onboarding entry point, answering queries like 'what can you do?'

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and suggests when to omit or specify topic. Provides clear context for when to use this vs. other tools.

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

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

Annotations indicate mutation (readOnlyHint=false), non-destructiveness (destructiveHint=false), and idempotency (idempotentHint=true). The description adds context by specifying that the row is deactivated (not deleted) and that history remains available, which aligns with annotations and provides deeper behavioral insight.

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 efficiently convey purpose, ownership, and behavior with no extraneous words or redundancy.

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

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

For a single-parameter tool with no output schema and clear annotations, the description fully explains the action, ownership constraint, side effects, and post-cancellation behavior, leaving no important gaps.

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

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

The input schema has full coverage (100%) and already describes the 'id' parameter as a subscription UUID from 'subscribe'. The description does not add new parameter semantics but reinforces the source; 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 specifies the action 'Cancel' and the resource 'subscription'. It distinguishes from sibling tools 'subscribe' and 'list_subscriptions' by explicitly focusing on cancellation and ownership enforcement.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding when the tool is applicable. It also explains the soft-delete behavior and references 'recent_alerts' for historical access, providing context for alternative tools.

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

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

Beyond the read-only annotations, the description discloses rich behavior: routing company-financial claims via SEC EDGAR+XBRL fast path, fallback to grounded pipeline for other facts, verdict enumeration, and critical distinction between could_not_verify (internal failure, no evidence) and unsupported (no source coverage). This adds substantial value beyond annotations.

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

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

Though a single long paragraph, it is front-loaded with trigger phrases and use context. Every sentence adds new information: routing, return structure, error semantics, and efficiency benefit. Nothing is redundant or wasted.

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

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

Given no output schema, the description compensates by explaining return values (verdict list, actual value with pipeworx:// citation, reasoning) and clarifying ambiguous verdict meanings. It also explains the two-tier routing for company-financial vs. all other claims, making the tool's behavior fully understandable.

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

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

Schema coverage is 100% and the schema descriptions are already detailed (e.g., tolerance_pct has 'Overrides the tolerance implied by the claim wording...'). The main description does not add further parameter semantics beyond what the schema provides, 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 a specific verb and resource: natural-language claim verification against authoritative sources. It distinguishes itself from siblings like ask_pipeworx and deep_research by framing it as fact-checking and highlighting that it replaces multi-step sequential calls.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides trigger phrases. It doesn't name specific alternative tools, but it does contrast with sequential calls, so while context is clear, it lacks explicit when-not/alternative tool exclusions.

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