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?

Beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description adds valuable behavioral context: it routes the question to the right tool, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is a 'one fast call' operation. No contradiction with annotations; the description enriches them meaningfully.

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

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

The description is long but densely packed with actionable information. It is front-loaded with the most critical directive ('PREFER OVER WEB SEARCH'), then systematically covers scope, examples, default status, and escalation paths. Every sentence earns its place; the length is justified by the tool's role as a default entry point.

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

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

Given that the tool has no output schema, the description fully compensates: it explains the tool's coverage (SEC filings, FDA data, FRED/BLS, etc.), the return format (structured answer with citation URIs), performance ('one fast call'), and tier availability. It also covers sibling differentiation and typical use cases, making the tool self-sufficient for an agent to select and invoke correctly.

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

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

The input schema has 100% coverage: the 'question' parameter is described as a natural-language request and even lists aliases (query, q, prompt, text, input). The description provides examples of valid questions, but these mostly reinforce what the schema already conveys. Since schema coverage is high and the description adds no unique parameter-level semantics beyond examples, the baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it routes factual questions to the appropriate one of 5,462 tools across 1,419 verified sources and returns structured answers with citations. It uses a strong verb ('routes') and resource ('Pipeworx'), and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by defining when each should be used.

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 'PREFER OVER WEB SEARCH' for questions about current/historical data, provides concrete examples of when to use it ('what is', 'look up', 'find', 'get the latest'), and gives clear alternatives ('Step up only when needed: use ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions'). This fully addresses when to use the tool vs. alternatives.

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

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

Beyond the readOnly/openWorld/idempotent annotations, it discloses the live candidate-testing behavior, the current inactive-candidate state (retired 2026-07-26), and that it falls back to nothing — it is fully functional. This adds valuable experimental context without contradicting annotations.

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

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

Four sentences front-load the core purpose, current status, usage, and fallback reassurance. Every sentence contributes meaning with no wasted words.

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

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

For a complex universal router, the description covers purpose, experimental status, usage, and clarifies potential misunderstanding about fallback behavior. Output shape is covered by 'same response shape,' so no output schema 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?

Schema coverage is 100% with all aliases documented; the description adds no additional parameter details beyond noting the same arguments as ask_pipeworx, which is redundant with the schema. Baseline of 3 applies because the schema does the heavy lifting.

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

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

The description explicitly states it is a beta version of ask_pipeworx, an identical universal router with the same 5,462 tools, arguments, and response shape, distinguishing it from the stable sibling by its experimental routing improvements. It clearly identifies the tool's role as a full working router.

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 directly instructs to use it 'when you want the newest routing' and notes it currently matches ask_pipeworx exactly, implying the stable tool as an alternative. It also clarifies it is a full working router, not a fallback, so the agent knows when to prefer 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?

Beyond the readOnly/idempotent annotations, the description discloses rich behavioral traits: the routing through 5,462 tools across 1419 sources, argument filling, data fetching, the extraction methodology (only from tool result), and the structured refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also describes the exact success return shape and the extra LLM call cost, providing full transparency about expected behavior.

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

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

The description is front-loaded with the most important purpose ('Hallucination-resistant answer mode for high-stakes reads') and uses two dense sentences to cover purpose, behavior, return format, refusal reasons, use cases, and cost trade-off. Every phrase adds value, and the structure separates the core explanation from the usage guidance, making it easy to parse.

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?

Without an output schema, the description completely specifies the return values, including the success object and all possible refusal reasons. It also accounts for the tool's complexity by describing the routing mechanism, the number of sources/tools, and the practical implications (extra LLM call, when to use). This makes the description self-sufficient for an agent to understand tool behavior and invocation context.

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

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

The input schema already provides 100% coverage, documenting the main 'question' parameter and five aliases. The description doesn't add parameter-level detail beyond clarifying that the tool takes a natural language question and routes it, which does not exceed the schema's existing clarity. Since schema coverage is high, the baseline of 3 is appropriate.

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

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

The description clearly defines the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and explains its core behavior: routing through the same tool selection as ask_pipeworx, fetching data, and extracting answers strictly from tool results. It explicitly distinguishes itself from the sibling ask_pipeworx by adding the extraction step and refusal mechanism, leaving no ambiguity about what it does.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups). It also states when not to use it: 'prefer ask_pipeworx for casual lookups,' and mentions the cost trade-off of one extra LLM call, giving clear decision criteria.

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?

The description goes far beyond the readOnly/idempotent annotations by disclosing the internal decomposition pipeline, parallel routing to 5,462 tools, output packet composition (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[]), semantic excerpting, latency expectations, and paid-tier behavior. 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?

Though long, the description is densely packed and every sentence carries operational value: account gating, scope boundaries, alternatives, output contract, edge cases, and latency. The most critical caveat (account requirement and fallback) is front-loaded, and no repetitive or filler content is present.

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

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

With no output schema, the description fully carries the burden of explaining return values and failure modes: it enumerates the findings packet fields, gap recovery, contradictions, and citation_uri resolvability. It also sets latency expectations and notes paid-tier distinctions, making the tool's behavior predictably complete for an agent.

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

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

The input schema already covers both parameters at 100% and describes the depth enum in detail. The description adds behavioral nuance—second-hop gap recovery, quick/standard/thorough follow-up semantics, and time ranges—which enriches interpretation beyond the schema, though it doesn't substantially alter parameter 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 names a specific verb and resource: 'multi-source research' across Pipeworx's 1419 STRUCTURED data sources with facet decomposition and parallel routing. It also distinguishes itself from sibling tools like ask_pipeworx by explicitly saying it is 'NOT open-web search' and explaining what niche it fills.

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

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

It gives explicit when-to-use guidance for broad/multi-part structured-data questions and when-to-use-alternatives for single lookups and breaking news. It also states account prerequisites and directs signed-out users to ask_pipeworx, making the decision boundary crystal-clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. 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?

The description discloses rate limits ('Rate-limited to 5 per identifier per day'), confirms it doesn't count against quota, notes the team reads digests daily, and emphasizes scope ('ONLY for tools served by this Pipeworx connection'). These behavioral traits go beyond the annotation hints, which are all false. No contradiction 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?

Although lengthy, every sentence delivers essential information: purpose, when to use, scope limitation, content guidelines, rate limit, and quota behavior. The structure front-loads the core purpose and flows logically from usage to caveats.

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

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

For a feedback tool with 3 parameters and no output schema, the description covers all necessary context: what to report, how to frame it, what happens after submission (digest), and constraints. It is fully self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100% with detailed parameter descriptions including enum meanings. The description adds extra guidance on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and specificity ('which tool, what error, what data was missing'). This supplements the schema meaningfully.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb and resource, and explicitly differentiates from sibling tools by focusing on feedback for Pipeworx tools only, not other vendors' tools.

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

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

The description provides explicit when-to-use scenarios: bug, feature/data_gap, praise. It also gives clear exclusions: 'if the tool came from a different MCP server... file it with that server instead.' This is excellent guidance for an agent deciding whether to invoke this tool.

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

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

The description 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?

Beyond annotations (readOnlyHint, etc.), the description discloses detailed behavior: two modes, response structure, safety fields, conditions for compatibility_warning, temporal alignment, and skipped cross types. It adds value over annotations by explaining what the tool actually does and when spreads are meaningless.

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 (around 20 sentences) but well-structured with sections for modes, response, and safety. It is front-loaded with the main purpose. However, some redundancy and verbosity could be trimmed. Still, every sentence adds value, 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 tool has no output schema, the description compensates by explaining the response structure (each venue's prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It covers all important aspects: modes, behavior, limitations, and safety. Completely sufficient for agent to use correctly.

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

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

Schema coverage is 100%, so the description does not need to add parameter meaning but it does: it lists the topic values, explains how explicit parameters override topic, and describes their interplay. This adds context beyond the schema, justifying a score above baseline 3.

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

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

The description clearly states the tool's purpose as computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the verb (compute spread) and resource (cross-venue). It distinguishes from siblings like polymarket_arbitrage by emphasizing the multi-venue comparison.

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

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

Provides explicit guidance on when to use (to see pricing differences) and when not (when compatibility_warning fires, temporal misalignment). It explains two modes (topic vs explicit) and warns that most pre-mapped topics return warnings, effectively setting expectations and preventing misuse.

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

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

Annotations already 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the agent knows it is a safe read operation. The description goes beyond this by revealing that 'each call cascades through several lookup endpoints internally' (performance behavior) and that results are auto-disambiguated. It also discloses the return format including specific citation URIs, which is valuable behavioral context.

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

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

The description is organized logically: example queries, core purpose, explicit usage instruction, then supported types with detailed output info. Most sentences carry unique information. The length is justified by the complexity of the tool, and front-loading the purpose makes it immediately scannable.

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

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

For a tool with no output schema, the description thoroughly explains return values, input variations, disambiguation, and citation URIs. It also implicitly differentiates from siblings like entity_profile by clarifying that it produces identifiers required for subsequent tool calls. The mention of replacing 2-3 manual lookups gives context about why this tool exists and when it is optimal.

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

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

While schema coverage is 100%, the description substantially enriches both parameters. For 'type' it explains what each enum value returns (company: ticker + 10-digit CIK + company_name + citation; drug: RxCUI + ingredient + brand + citation). For 'value' it details accepted formats (ticker, CIK, or name; brand or generic) and adds disambiguation behavior. This goes well beyond the schema's one-line property 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 begins with concrete example queries and states the core purpose: resolve a user-spoken NAME to the canonical/official identifier other tools require. It clearly specifies the verb ('resolve') and resource ('entity'), and distinguishes itself from sibling tools by noting that other tools need these identifiers as input.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID,' which gives a clear when-to-use directive. It also describes supported types and input flexibility (ticker, CIK, name for company; brand/generic for drug), and mentions that it replaces 2-3 manual lookups, framing the tool as the preferred entry point for identifier resolution.

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 annotations (read-only, open-world, idempotent), the description discloses key behavioral traits: it uses two distinct paths (SEC EDGAR for financial claims, grounded pipeline for others), returns specific verdict types with evidence, and applies percent-delta math. This adds substantial context 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 comprehensive but slightly lengthy; however, every sentence contributes meaningful information. It is well-structured, starting with the core purpose, then detailing the two processing paths, and concluding with output and efficiency claims. Minor redundancy 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?

Given the complexity of the tool (two processing paths, parameter options, no output schema), the description fully explains behavior, return values (verdict, actual value, citation), and reasoning. It covers both fast-path and fallback, making it complete 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?

The input schema already documents both parameters with descriptions, achieving 100% coverage. The description adds nuance by explaining how 'tolerance_pct' overrides the implied tolerance and provides usage examples for hallucination detection, thus adding 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 explicitly states the tool's purpose as natural-language claim verification against authoritative sources, with specific example triggers like 'Is it true that...' and 'fact check'. It distinguishes between financial and general claims, clearly communicating the scope and action.

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

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

The description provides clear guidance on when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It implicitly suggests it replaces multiple sequential calls but doesn't explicitly contrast with sibling tools like 'ask_pipeworx_grounded' or 'deep_research', which could serve similar purposes.

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