catfacts

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable operational behavior: defaults to a free Workers AI model, requires a BYO Anthropic key with direct cost, and returns per-model score/confidence/signals/raw_response plus a combined view. 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?

Three compact sentences, front-loaded with the main function. Every sentence adds functional value (purpose, defaults/cost, return format and use cases), with zero 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 is complete for this tool: full schema descriptions, strong annotations, clear return shape, and explicit use cases. No output schema exists, but the described per-model structure and combined view are sufficient for an agent to understand 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% for all 4 parameters. The description further clarifies the models/_apiKey relationship by noting the default free model and BYO key cost, which adds meaning beyond the schema. It also helps understand the output that parameters influence.

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

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

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

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), which tells an agent when to invoke it. Though it doesn't name specific alternative tools, the context is clear enough to guide selection.

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 behavioral context: returns structured answers with pipeworx:// citation URIs, works on every tier, and one fast call. It also clarifies that it routes to live news for opinion questions.

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

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

The description is detailed but each sentence serves a purpose: it starts with the key recommendation, explains for which topics, provides examples, and gives escalation paths. It is well-structured and not redundant.

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 that routes across many sources, the description effectively covers scenarios, alternatives, and output behavior. It addresses potential confusion about breaking news and provides a clear starting point recommendation, making it complete for the agent.

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

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

Schema coverage is 100% with descriptions for the question parameter and aliases. The tool description supplements this with concrete example questions ('current US unemployment rate', 'Apple's latest 10-K'), which demonstrate expected input formats.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and states it 'Routes the question to the right one of 5,529 tools...' This clearly identifies the tool as a routing/querying aggregate, distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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 'START HERE for most questions' and 'Step up only when needed', naming specific alternatives (ask_pipeworx_grounded, deep_research) and when to use them. Including example queries further clarifies scope.

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

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

Adds valuable context beyond annotations: candidate routing is enabled live only when a candidate is under test, currently no candidate is active, it is a full working router not a fallback, and the response shape matches ask_pipeworx. No contradiction with the readOnly/idempotent hints.

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

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

The description is dense but every sentence contributes: beta status, identical scope, current candidate state, usage instruction, and fallback clarification. The parenthetical date is slightly extra but supports transparency.

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-required-param router with rich annotations and full schema coverage, the description sufficiently explains current behavior and relationship to ask_pipeworx. It does not detail the return format beyond 'same response shape,' but that is acceptable given the sibling reference.

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 of all 6 parameters, including alias descriptions. The description only says 'same arguments' and does not add parameter-level syntax or formatting details, so it stays at the baseline.

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

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

The description clearly identifies the tool as a beta universal router identical to ask_pipeworx, with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by framing it as the experimental edge with candidate routing improvements.

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 directs the agent to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared with the stable router. It does not enumerate when not to use or mention ask_pipeworx_grounded, but the usage context is clear.

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

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

The description discloses significant behavioral details beyond annotations: it returns a refusal with specific reasons when data doesn't directly answer, and it costs an extra LLM call. These traits are not implied by the readOnly/idempotent annotations, adding valuable expected behavior information.

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

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

The description is dense but every sentence contributes: purpose, routing mechanism, return format, refusal conditions, usage guidance, and cost tradeoff. It front-loads the core value proposition and remains well-organized despite its length.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly covers the full behavior: success return shape, failure modes with refusal_reason, use cases, and cost. No critical gaps remain for an agent to properly select and invoke this tool.

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

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

The schema fully covers the parameters (100% coverage), including the question field and its aliases. The description adds no parameter-specific semantics beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode that extracts answers solely from tool results. It distinguishes itself from sibling ask_pipeworx by emphasizing evidence, confidence, and explicit refusal behavior, making it specific and actionable.

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 defines when to use the tool ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). It also names the alternative, ask_pipeworx, and explains the extra LLM call cost.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses major behaviors: low-confidence matches short-circuit with status, closed markets skip fan-out, wide spreads carry tradeability warnings, and resolution-rule risk with refund_50_50. These are genuine behavioral traits that help agents anticipate side effects and 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 more verbose than typical tools, but it is well-structured with clear section headers and front-loaded purpose. Every section (classifiers, fan-out examples, resolver contract, safety) adds distinct value, so the length is justified though not perfectly concise.

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

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

With no output schema, the description carries full burden for return values, and it delivers: market fields, analysis fields, evidence keys, resolver contract, parent_event extraction, news fallback, and safety behaviors. It also covers edge cases like cancellation rules and illiquid markets, making it complete for a complex research tool.

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

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

Schema already documents all three parameters with detailed descriptions and examples (100% coverage). The description adds fan-out context but does not add meaning beyond what the schema's parameter definitions already provide, so baseline 3 applies.

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

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

Description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on evidence gathering and explicitly stating use cases ('should I bet on X', 'what does the data say about Y').

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 for when to invoke the tool ('Use for...') and shows fan-out examples for different bet categories. It does not explicitly name alternatives or when-not-to-use scenarios, but the context is clear enough to guide agent selection.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses data sources (SEC EDGAR/XBRL vs FAERS), specific metrics pulled, off-calendar fiscal-year handling, result sorting, and citation URI output. This gives substantial behavioral context the annotations alone would not convey.

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

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

The description is dense and front-loaded with common query patterns before the core statement, with every sentence carrying useful information. However, it is a long single paragraph that could be better segmented for scannability.

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

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

With no output schema, the description compensates by summarizing the return format (paired data + citation URIs), sorting behavior, scope (2–5 entities), and the tool's advantage over sequential lookups. It covers key edge cases like off-calendar fiscal years, making it sufficiently complete.

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

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

Schema coverage is 100%, including enum descriptions and array constraints. The description adds meaningful semantics by specifying what each entity type pulls (company: 10-K financial metrics; drug: adverse-event/FDA/trial counts) and notes sorting by primary metric, though it leaves 'primary metric' somewhat underspecified.

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+resource ('side-by-side comparison of 2–5 companies or drugs') and immediately distinguishes itself from sibling single-entity lookups. It clearly states this is the preferred tool for comparison queries and gives concrete trigger phrases.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear when-to-use rule and exclusion of the alternative approach. The trigger examples ('X vs Y', 'rank these companies') further guide when the tool is appropriate.

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 annotations, disclosing account/pricing requirements, the NOT open-web nature, latency, return packet structure, gaps[] behavior, contradictions[], hop field, citation resolvability, semantic excerpting, and the guarantee never to invent answers. No contradiction with the readOnly/openWorld/idempotent annotations is present.

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

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

The description is long but every sentence adds necessary context for a complex tool. It is front-loaded with the account requirement and core distinction, then flows through examples, alternatives, depth semantics, output details, and timing. The single-paragraph format is dense but well-organized; slight trimming could improve scannability.

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

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

Given the tool's complexity, no output schema, and rich annotations, the description is exceptionally complete. It covers not only inputs and outputs but also failure modes (gaps when topic absent), citation fetchability, contradiction detection, latency expectations, and plan differences—leaving little ambiguity for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial semantic value: it explains how depth affects facet count, hop behavior, gap recovery, contradiction scanning, and pricing. It clarifies that question can be broad/multi-part and that decomposition is intended. This exceeds schema-only 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 defines deep_research as grounded multi-source research over Pipeworx's structured data sources, explicitly distinguishing it from open-web search and from ask_pipeworx. It specifies the resource (1455 data sources, 5529 tools), the action (decomposes, routes, returns findings packet), and the output format.

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

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

Provides explicit guidance: use ask_pipeworx for single lookups, for breaking/current-news topics, or when not signed in. Describes depth-level choices and when to prefer standard/thorough for multi-step questions. Clearly names sibling alternatives and their contexts.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds useful context about the return format (top-N tools with schemas and curated examples) and the 'ready to call directly' behavior, which is beyond what annotations provide.

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

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

The description is somewhat long due to the extensive domain list, but every sentence earns its place: it states purpose, gives usage context, and explains output behavior. It is front-loaded with the core verb and resource.

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

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

Since there is no output schema, the description fully explains what is returned: top-N tools with names, descriptions, and full input schemas. It also provides the important context to call this tool first when many tools are available, making it complete for decision-making.

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 the concept of 'top-N' and 'query as natural language description' but these are also present in the schema. It does not provide meaningful extra parameter-level detail.

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

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

The description uses a specific verb 'Find tools' and clearly states the resource (tools) and purpose (describing the data or task). It distinguishes itself from siblings by positioning as a meta-tool for discovery, listing concrete data domains it covers.

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 you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available'. It implies when not to use (when you need a single answer) but does not name alternative tools explicitly.

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 the multi-source fan-out (SEC, XBRL, USPTO, news, GLEIF), the exact return fields with URIs, the patents soft-fail due to API sunset, and the GDELT→GNews fallback. This goes well beyond the readOnly/idempotent annotations and aligns with them, with no contradiction.

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

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

The description is a single dense paragraph but front-loaded with examples and core purpose. For a tool with this complexity (multi-source fallback, return fields, constraints), the length is justified, though better use of bullet points or sections would improve scannability.

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

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

With no output schema, the description thoroughly documents the complete return structure (cik + company_name, recent_filings with URIs, fundamentals with sorting, patents, news fallback, LEI). It also provides input limitations and failure modes, making it complete for an agent to understand what to expect.

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 has 100% coverage: type is described as an enum with only 'company' supported, and value explicitly mentions ticker/CIK formats and that names are not supported. The description repeats this information and adds examples, but does not meaningfully extend the schema semantics, so 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 it provides a 'full cross-source profile of a US public company' with specific prompts like 'Tell me about X' and 'research Acme'. It distinguishes itself from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and clarifies the input constraints (ticker/CIK vs. name).

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 prefer this tool ('when the user asks for a holistic view') and directs use of resolve_entity when only a name is provided ('Names not supported (use resolve_entity first)'). It also mentions the patent API sunset and soft-fail behavior, giving clear expectations.

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, so the description doesn't need to restate that. It adds marginal context ('clear sensitive data') but doesn't disclose behavior beyond annotations, such as what happens if the key doesn't exist.

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, first states the core action, second provides usage context. No filler or redundancy; every word earns its place.

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

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

For a simple 1-parameter, no-output-schema tool with annotations covering destructive and idempotent behavior, the description provides purpose, timing, and relationships to siblings. It omits only minor details like return value or missing-key behavior, which are not critical given the simplicity.

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% — the only parameter 'key' is already fully described as 'Memory key to delete'. The description adds no further 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 uses a specific verb ('Delete') and resource ('previously stored memory') along with the mechanism ('by key'), which clearly distinguishes it from sibling tools like remember and recall. It also names the action context (clearing sensitive data).

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

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

The description explicitly states when to use the tool ('context is stale, the task is done, or you want to clear sensitive data') and even directs pairing with remember and recall, giving clear context versus alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds that it fetches the page and emits a standard markdown blob, which is useful behavioral context beyond the annotations. It does not go into failure modes or rate limits, but given the rich annotations, it meets a baseline.

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-loaded with the core action, followed by process, output format, and use cases. No redundant phrases; 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?

With two simple parameters, a well-described output ('single text blob' in standard llms.txt format), and rich annotations, the description is sufficient for an agent to understand and invoke the tool correctly. The 'Useful for' section adds practical 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?

Input schema covers 100% of parameters with descriptions (url and max_links with default/max). The description does not repeat parameter details, but the schema carries the burden; no additional semantic value is added.

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

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

The description uses the specific verb 'Generate' with the resource 'llms.txt file for any URL', then elaborates the process (fetches, extracts, emits). This clearly distinguishes it from sibling tools like ai_visibility_check, which focus on visibility measurement rather than file generation.

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

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

Provides a clear 'Useful for' list with three concrete use cases (client site indexing, personal project drafting, competitor auditing), giving context for when to use. However, it does not name alternatives or explicitly state when not to use it, though the sibling list includes potentially overlapping 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 already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the 'random' nature of the fact and the specific return fields (fact text and character length), which are behavioral details beyond the annotations. It does not mention any edge cases, but for a simple read-only tool this is sufficient.

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

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

The description is two sentences, front-loaded with the primary action, then the return value, and finally the alternative. Every sentence contributes meaningful information with no redundancy or filler.

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

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

For a zero-parameter tool with strong annotations (read-only, idempotent, non-destructive) and a defined output schema, the description provides sufficient detail: what it does, what it returns, and when to use the sibling tool. There are no gaps for this level of complexity.

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

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

The tool has zero parameters and the schema coverage is 100%, so there are no parameter semantics to explain. The baseline for zero parameters is 4; no additional explanation is needed or provided. The description does not need to add parameter information.

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

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

The description clearly states 'Get a random cat fact' with a specific verb and resource, and further specifies what is returned ('fact text and character length'). It also distinguishes from the sibling tool get_facts by indicating this one retrieves a single fact. This is a clear, specific 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?

The description explicitly says 'Use get_facts to retrieve multiple facts at once,' providing direct guidance on when to use this tool versus the alternative. This is explicit and actionable usage guidance.

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

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

Beyond the read-only, idempotent, and non-destructive annotations, the description discloses that facts are random and that it returns an array of fact texts with character lengths, adding useful behavioral context. It does not mention the default count, but the schema covers that.

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

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

The description is two sentences, front-loaded with the core action, and every sentence earns its place. No redundant or filler content.

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, full annotations, and output schema, the description is complete: it covers purpose, randomness, count specification, and return format. No significant 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?

The schema provides full coverage for the 'limit' parameter with a description and default value. The tool description adds an example ('e.g., 5') but no additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Get'), resource ('multiple random cat facts'), and scope ('at once'), clearly distinguishing it from the singular sibling get_fact. It also mentions specifying a count, which clarifies the tool's function.

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

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

The description gives clear context: use this tool when you need multiple random cat facts at once. It does not explicitly mention alternatives or exclude single-fact usage, but the plural language implies the distinction from get_fact.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description doesn't need to restate those. It adds value by mentioning the return fields. However, it fails to disclose that no filtering parameter exists; instead, it implies search-by-name is available, which is a transparency gap.

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

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

The description is two sentences long, front-loaded with the main action, and every word contributes. It is concise and well-structured with 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?

Given the simple tool (one optional param, no nested objects, output schema present), the description is mostly sufficient. However, the unsupported 'search by name' claim makes it incomplete because the description doesn't clarify the actual scope (only limit-based listing) and could lead to incorrect 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?

The schema has 100% coverage for the single parameter (limit), so the description doesn't need to explain it. However, the description introduces a 'search by name' capability without a corresponding parameter in the schema, which actively misleads the agent about the tool's filtering capabilities.

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 primary action (list cat breeds) and specifies the domain (cat breeds), which distinguishes it from unrelated sibling tools. However, it also claims a 'search by name' capability that is not supported by the input schema (which only has a 'limit' parameter), making the purpose slightly misleading.

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 when to use the tool: to search or list cat breeds. It implies two usage modes (by name or all), but it does not explicitly mention alternatives or exclusions. Given that sibling tools are in unrelated domains, this level of guidance is acceptable.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context by specifying the scope ('caller's active subscriptions') and the exact return fields, which goes beyond the annotations and gives the agent a clear expectation of the tool's behavior. It stops short of prescribing pagination or ordering details, but for a simple filtered list tool this is sufficient.

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 composed of two sentences, the first stating the main purpose, the second listing return fields and usage context. There is no redundancy or filler; every sentence earns its place, making it highly concise and well-structured.

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

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

Given the tool's simplicity (one optional parameter, no output schema, rich annotations), the description is complete. It explains what the tool does, what data it returns, and when to use it, leaving no significant gaps for the agent to guess.

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 include_inactive with a complete description, so schema coverage is 100%. The tool description does not add extra meaning about the parameter beyond repeating the 'active' notion, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'List the caller's active subscriptions.' It uses a specific verb-resource pair and further specifies the returned fields (id, type, params, created_at, etc.), making it easy to distinguish from sibling tools like subscribe or unsubscribe which perform different actions.

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 provides usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly tells the agent when to invoke this tool relative to subscribe (before adding) and unsubscribe (finding id), which is excellent guidance and distinguishes it from 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?

While annotations are all false, the description adds substantial behavioral context beyond them: filing returns a claim_token, passing it later returns status and resolution details, the report is rate-limited to 5 per identifier per day, feedback is free and doesn't count against quota, and the team reads digests daily. This fully discloses side effects, limits, and lifecycle behavior without contradicting any annotation.

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

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

The description is long but every sentence serves a purpose: purpose, usage triggers, exclusion scope, claim-token workflow, rate limit, and roadmap impact. It is front-loaded with the core action then flows logically into conditions and constraints. No redundant filler; each clause adds behavioral or contextual detail that an agent needs.

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

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

Given the absence of an output schema, the description fully covers what to expect: a claim_token on filing and later status/changes when reclaimed. It addresses the tool's scope (only Pipeworx tools), the feedback categories, and operational limits. The parameter count (4) and nested context object are adequately explained, making the tool fully usable from the description alone.

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

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

The schema already provides 100% coverage with detailed descriptions for all four parameters. The description adds semantic value by explaining the practical use of claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and advising to 'not paste the end-user's prompt,' which clarifies the expected content for the message parameter. It also reiterates the type categories in prose, reinforcing schema enums but not duplicating them excessively.

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

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

The description opens with a clear, specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact feedback categories (bug, feature/data_gap, praise), making the tool's purpose unmistakable. It also distinguishes itself from siblings by scoping to 'tools served by this Pipeworx connection,' a differentiation absent in other tool descriptions.

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

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

Explicitly states when to use the tool ('Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)') and when not to ('if the tool came from a different MCP server... file it with that server instead'). It also gives concrete naming guidance for feedback content, which is actionable and helps the agent decide.

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

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

Beyond annotations (readOnly, idempotent), the description discloses additional behavioral traits: self-aggregating signal, no PII, derived from CF analytics-engine, and caching (5min-1h). This enriches the agent's understanding of data freshness and privacy without contradicting annotations.

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

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

The description is well-structured and succinct: a clear one-sentence summary, a bulleted list of three use cases, and a concise note on data sourcing and caching. Every sentence adds value, with no redundant content.

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

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

Despite having no output schema, the description specifies return contents (top tools, top packs, total call volume, and raw (pack, tool, count) data). It also explains caching and data source, making the tool's behavior fully understandable for a simple one-parameter interface.

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 for the single parameter 'window' is 100%, but the description adds interpretive meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema's enum/description, providing decision-making nuance.

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: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('returns') and resource, and differentiates itself from siblings by focusing on aggregated trending data rather than individual queries or entity lookups.

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

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

The description provides explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with other agents' needs. It implies when to use this tool without naming specific alternatives, but gives clear context for application.

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

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

Annotations already establish read-only/idempotent safety, but the description adds substantial behavioral detail: monotonicity + partition-sum methodology, the 3pp threshold, semantic similarity anchor (≥0.30 Jaccard), placeholder filter (20% fraction → null arb), and the critical fill check statement that realizable_edge_pp ≤ 0 means 'do not trade it.' This goes far beyond the annotation hints.

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

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

The description is a dense, run-on paragraph covering many modes, filters, and response details. It is front-loaded with the purpose but exceeds reasonable length and lacks visual structure (bullets/headings). While every sentence carries value, the overall form is not concise and hampers quick scanning.

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 2-param tool with no output schema, the description fully covers the response shape (opportunities[], partition_check{}, fill check fields), edge cases (skipped_low_similarity, placeholders_filtered), and explicit warnings. It anticipates user questions about semantics and safety, leaving little ambiguity.

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

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

Both event and topic are optional and schemas already cover 100%, but the description elevates meaning by explaining mode-specific behavior, recommended usage, examples, and response differences (e.g., partition_check in event mode). The alternatives are clearly contrasted, making the parameter roles unambiguous.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket' and immediately distinguishes three invocation modes (no-args trending_scan, event, topic), clearly separating it 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?

Explicitly explains when to use each mode: event is 'recommended for a specific market,' topic is for cross-event scanning and catches patterns single-event misses, and it directs custom sizing to polymarket_fill_risk. Provides concrete example slugs and seed questions.

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

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

Despite annotations already declaring readOnlyHint=true and idempotentHint=true, the description adds extensive behavioral context: the three model segments, edge calculation details, slippage netting, Kelly caps, 24h-move warnings, diagnostics funnel, and 1h KV-level caching. This far exceeds what the annotations alone convey.

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 extremely dense and runs as a single long paragraph without section breaks. While information-rich, it could be better organized with shorter paragraphs or bullet-like structure. The length is largely justified by the tool's complexity, but it is not concise.

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

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

With no output schema present, the description fully covers the return value: by_segment structure, fed_candidates/fed_note, diagnostics, and why segments might be empty. It also covers caching, slippage assumptions, and edge-case details, making it highly complete for a complex tool.

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

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

All 9 parameters are fully described in the input schema, so the schema carries heavy weight. The description complements this by explaining how tradeable-edge knobs (min_liquidity, max_spread_pp) interact and clarifying the subtle behavior of min_partition_leg_kelly (parent-level kelly always 0). 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 first sentence clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, giving a specific verb, resource, and scope. The detailed model-family breakdown and response segments further distinguish it from sibling Polymarket tools, even though no alternatives are explicitly named.

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

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

The description gives a clear intended use case ('what should I bet on today') and explains that Fed bets are excluded due to unreliable data. However, it does not explicitly mention when to use this tool instead of siblings like polymarket_arbitrage or polymarket_edge_tracker, so exclusions/alternatives are missing.

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

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

Annotations already declare readOnly/idempotent/destructive flags; the description adds valuable caveats about the 60-day snapshot TTL, dependence on snapshotting being enabled, and that decay numbers come from daily closes rather than intraday. These behavioral details go beyond what annotations provide.

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 lengthy but information-dense, including purpose, args, response payload, and data caveats. Each section earns its place, though it could be slightly trimmed. It is well-structured with clear sections for args and response.

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

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

No output schema exists, so the description thoroughly specifies the response format: tracked[] with edge_pp_net time-series, trend, decay_pp_per_day; expired[] with lifespan_days; and snapshot_dates[] with data-gap semantics. Limits such as TTL and data start time are also disclosed, making the tool's behavior fully transparent.

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

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

Schema coverage is 100% and both parameters are described in the schema itself (days with lookup/clamp, window with enum values). The description reiterates these values ('default 14, max 30', 'default 1wk') and adds the context that window refers to a 'snapshot family', but does not significantly extend 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?

Description states it provides 'edge persistence and decay telemetry built from daily polymarket_edges snapshots' and directly addresses the question 'how long has this edge existed and is it shrinking?' This clearly distinguishes it from sibling polymarket_edges which likely surface current edges.

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

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

The description contextualizes usage by explaining the trade-off between fresh and old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'), making the intended use clear. It does not explicitly name alternatives or when-not-to-use, but the framing is sufficient.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond these by detailing internal behavior (walks the ladder, returns top-of-book vs VWAP), output fields (verdict, thin_legs), and risk context (partial basket fills convert an arb into an unhedged directional position). No contradiction with annotations.

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

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

The description is long but every sentence carries essential information. It is front-loaded with the core purpose, then organized into explicit mode sub-sections and output enumerations. No fluff or repetition; the length is justified by the tool's complexity.

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

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

Despite having no output schema and high complexity (two modes, many outputs), the description comprehensively details return values (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, etc.), risks (forced_directional_risk), and usage preconditions. It is complete enough for an agent to decide when and how to invoke the tool correctly.

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

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

Although the schema provides 100% coverage, the description adds significant semantic layer: size_usd is interpreted differently in single-market (max spend/target proceeds) vs basket (settlement notional per share paying $1), and side defaults are explained (auto for basket based on partition sum). This clarifies ambiguity beyond bare parameter descriptions.

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

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

The description starts with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools (polymarket_arbitrage, polymarket_edges) by stating it is the fill-risk check to use before acting on their signals. The two modes (single-market and basket) are also clearly articulated.

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

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

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the alternative scenarios for single-market vs basket mode and warns against using it when theoretical overround is not capturable on thin books.

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 beyond the readOnlyHint and idempotentHint annotations by detailing edge cases: compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype counters, and the realistic rarity of tradeable spreads. This gives the agent a clear model of the tool's limitations and failure modes.

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

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

The description is long but well-structured with clear sections (modes, response, safety fields). It front-loads the core purpose and then provides necessary detail for a complex tool, avoiding redundancy while remaining dense with useful information.

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

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

With no output schema, the description carries the burden of explaining return structure: leg-by-leg prices, matched spread[].top_spreads_pp, and safety fields. It also explains temporal alignment and skipped-cross counters, making the tool's behavior fully comprehensible for an AI agent.

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

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

The input schema already covers all parameters with descriptions, so baseline is 3. The description adds value by explaining the mode semantics, listing the exact topic shortcuts, and clarifying that explicit tickers 'override' the topic-mapped side, plus interpreting response fields like matched_spread[].top_spreads_pp.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly identifies the tool's function and scope. It distinguishes itself from sibling tools like polymarket_arbitrage by explicitly targeting cross-venue comparisons and detailing two modes of operation.

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 thoroughly explains when to use each mode: the 'topic' shortcut for pre-mapped macro events and explicit tickers for custom pairings. It also warns that 'pre-mapped ≠ tradeable' and explains compatibility warnings, but it does not explicitly contrast with alternative sibling 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: listing all keys when key is omitted, scoping to identifier, and pairing with remember/forget. It doesn't contradict annotations, but doesn't mention edge cases like missing keys or return format.

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

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

The description is four sentences, each packed with relevant information: primary action, use case, scoping, and tool pairing. No fluff or repetition; it is front-loaded with the action and structured logically.

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

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

The tool is simple (one optional param, no output schema), and the description covers purpose, usage, scoping, and sibling relationships. It lacks explicit notes on return values or error handling, but these are not critical for this simple tool. Overall, it is sufficiently complete.

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

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

Schema coverage is 100% (the 'key' parameter is fully described). The description reinforces the parameter behavior (omit to list all keys) and adds examples of what keys might contain, but doesn't add substantial new meaning beyond the schema. 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 primary action ('Retrieve a value previously saved via remember') and secondary behavior ('list all saved keys (omit the key argument)'), using a specific verb and resource. It distinguishes itself from siblings by naming 'remember' and 'forget' and giving concrete examples like 'ticker', 'address', and 'research notes'.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives (remember, forget) and notes scoping to identifier, providing clear context for when to use versus 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?

The description discloses a side effect: setting mark_read=true flags returned events as read, altering subsequent calls. This directly contradicts the annotations' readOnlyHint=true, which asserts the tool is read-only. Since the description contradicts the annotation, score is 1 and annotation_contradiction=true.

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

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

The description is compact and front-loaded, with no redundant sentences. It covers purpose, return fields, filtering, mark_read behavior, and an alternative access method in a few sentences of appropriate length.

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

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

The description is comprehensive for a read tool with 5 optional parameters: it explains return payload structure, filtering, side-effect parameter, and provides an alternative endpoint. Given the annotations and schema coverage, it equips the agent to use the tool correctly.

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

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

Schema describes all 5 parameters with 100% coverage. The description adds detail about mark_read's effect ('so the next call only shows newer ones') and implies filtering use, but the schema already documents these. It doesn't add significant semantics beyond the schema.

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

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

The description opens with 'Pull fired events from your subscription feed,' which is a specific verb+resource. It clearly distinguishes from siblings like list_subscriptions (listing subscriptions) and recent_changes (tracking changes) by focusing on fired events from the feed. The mention of 'evaluator' and 'persisted feed' adds specific context.

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 clear usage context: it mentions that polling works fine and offers an alternative URL for scripts and dashboards, implying this tool is for interactive/polling use. However, it doesn't explicitly contrast with sibling tools like recent_changes or ask_pipeworx, so the guidance is clear but not exhaustive.

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

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

Annotations already declare read-only and idempotent; description adds multi-source fanout behavior, GDELT→GNews fallback, USPTO soft-failure context, and return structure (changes[], total_changes, citation URIs), going well beyond annotation info.

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

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

Dense but every clause delivers value: query intents, source list, parameter options, return shape, and alternative. Front-loaded with purpose despite length, no filler.

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

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

For a complex multi-source tool with no output schema, description covers return values, source behaviors, fallbacks, and caveats (USPTO sunset). Sufficient for an agent to understand capabilities and constraints.

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 all 3 parameters with descriptions (100% coverage). Description repeats since/value semantics without adding new syntactic meaning, so baseline 3 applies.

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

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

Description explicitly states it provides a change feed for a company over a window, with clear query examples. Distinguishes from entity_profile by contrasting static vs dynamic profile, fulfilling sibling differentiation.

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

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

Provides typical user prompts ('What's new with X') and explicitly recommends entity_profile for static profile needs, offering a clear when-to-use vs alternative. Also gives practical guidance on since parameter for typical monitoring.

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

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

Despite annotations (idempotentHint, destructiveHint), the description adds critical context: 'Stored as a key-value pair scoped by your identifier' and 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' These retention and scoping details are not in the annotations.

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

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

The description is concise and front-loaded with the core purpose, followed by usage context, storage details, and sibling pairing. Each sentence adds meaningful information without redundancy, earning its place.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, usage, persistence, retention, and sibling relationships. The annotations plus this description give the agent everything needed 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?

The input schema already covers 100% of parameters with descriptions. The description adds value by giving concrete examples ('a resolved ticker, a target address, a user preference') and defining value as 'findings, addresses, preferences, notes', enriching 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's function: 'Save data the agent will need to reuse later'. The verb 'Save' and resource 'data' are specific, and it distinguishes itself from siblings by explaining the key-value storage and pairing with recall/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 explicit 'Use when' guidance: 'when you discover something worth carrying forward... so you don't have to look it up again.' It also names complementary tools: 'Pair with recall to retrieve later, forget to delete,' clarifying when to use this 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 annotations (read-only, idempotent, etc.), the description adds valuable behavioral context: identifiers are labeled with sources, unresolved identifiers are explicitly included under `unresolved`, and LEI/FIGI enrichment degrades gracefully with EDGAR identifiers still returning. This goes well beyond the annotation hints.

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

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

The description is substantial but every sentence earns its place. It is front-loaded with illustrative queries, then the core purpose, then detailed type-specific behavior. The structure is logical and avoids fluff despite its length.

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

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

For a lookup tool with no output schema, the description is unusually complete: it covers input formats, output identifier sources, unresolved handling, fallback behavior, and the fact that it replaces multiple manual lookups. Given the tool's complexity, this is well-rounded and sufficient.

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

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

Schema coverage is 100% and the description mostly restates the schema's parameter descriptions (e.g., ticker/CIK/name for company, brand/generic for drug). It adds some contextual enrichment about what each type resolves to, but does not significantly extend parameter semantics 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: resolving user-spoken names to canonical/official identifiers required by other tools. It provides concrete example queries and clearly distinguishes the resource and action, making it unambiguous and useful for tool selection.

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 clear guidance: "Use FIRST whenever you have a name but need an ID." It also specifies supported entity types and input formats. However, it does not explicitly mention when not to use it or name alternatives, though the guidance effectively narrows usage.

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. The description adds behavioral context beyond those: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. This adds transparency regarding internal mechanism and output, without contradicting the annotations.

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

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

The description is concise and front-loaded: the first sentence states the core action, the second explains the mechanism, the third gives a use case, and the fourth lists return fields. Every sentence earns its place with no redundancy or fluff.

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

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

Given there is no output schema, the description appropriately describes the return value ('ranked list with score, confidence, signal density per entity'). It also explains the tool's relationship to sibling ai_visibility_check and covers the competitive audit use case. This is complete for a tool with 4 parameters and a single required field.

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 each parameter (models, _apiKey, context, entities) already described in the input schema. The description does not add new parameter semantics beyond what the schema states (e.g., first entity as subject, rest as competitors). Since schema covers all params, baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies a concrete verb ('Compare'), a resource ('AI visibility'), and the scope ('multiple entities'). It also distinguishes from sibling tool ai_visibility_check by emphasizing multi-entity comparison, ranking, and output specifics.

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, stating it is 'Useful for competitive AI-marketing audits' and gives an example with a concrete query. It implicitly differentiates from single-entity sibling ai_visibility_check by focusing on multiple entities, but it does not explicitly state when not to use this tool or name alternatives as 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 declare readOnly/idempotent/non-destructive, and the description adds valuable behavior: composite fan-out, partial failure degradation, bundlephobia's first measurement taking 5-30s, and the sources_failed field. This exceeds what annotations provide.

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

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

The description is longer than typical but well-structured: purpose, usage, return values, ecosystem scope, and failure handling each earn their place. Front-loaded with the purpose, making it easy to scan.

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 enumerates return fields (summary block, advisories, links, versions), describes failure modes and timing, and states ecosystem limitations. This makes the tool's behavior predictable and 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 description coverage is 100%, so the baseline is 3. The description adds minimal parameter-specific semantics beyond the schema, though the NPM-only ecosystem note adds context for the package parameter.

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

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

The description clearly states it is a composite 'should I add this npm package' check, listing the sources (deps.dev, bundlephobia) and the specific question it answers. This distinguishes it from sibling research tools, which focus on other domains.

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 whenever an agent asks is X safe / popular / small or what does adding lodash cost me.' It also specifies NPM-only in v1 and directs PyPI/Maven/Cargo/Go to deps.dev:version directly, providing clear exclusion guidance.

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

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

The description discloses behavioral details beyond annotations: it returns top-N passages with character offsets and similarity scores, specifies underlying embeddings (BGE-base-en) and chunking (500-char windows), and states the 200K char limit with truncation behavior. This enriches the safe-read profile defined by annotations.

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

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

The description is dense but every sentence serves a purpose: main action, use case, pairing info, technical details, and limits. It is front-loaded with the core purpose and structured logically, 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?

Given no output schema, the description compensates by describing return format (passages with offsets and scores), technical behavior (embedding model, window size), and edge cases (truncation). Combined with 100% schema coverage and strong annotations, the description fully covers what an agent needs.

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 contextual meaning by giving examples of 'text' (SEC 10-K, article) and query examples, plus the practical motivation for passing text directly. This adds value beyond the schema's basic parameter descriptions.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the resource (record text) and the action (search). It distinguishes itself from siblings by positioning it as a context-saving alternative to ask_pipeworx_grounded and by emphasizing character offsets for verification.

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

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

Explicit usage guidance is provided: use when the record is too large for the prompt, pair with ask_pipeworx_grounded, and leverage offsets to verify quotes. This gives clear when-to-use and alternative tool connections.

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 a non-read-only, idempotent, non-destructive operation. The description adds substantial behavioral detail: OAuth requirement, inability to persist for anonymous/BYO, always-on feed with pull endpoints, phone verification requirement, 10/day SMS cap, webhook signing secret returned once, and auto-disabling after 10 consecutive failing runs. This goes far beyond the annotations and provides crucial side-effect and prerequisite information.

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

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

The description is front-loaded with the core purpose and then expands into requirements, types, and delivery. It is dense but each sentence carries actionable information without fluff. It is longer than typical descriptions but appropriately so given the complexity of multiple subscription types and delivery options. It is structured with clear separators, making it easy to scan.

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 at least mentions the return value (subscription id) but could go further by explaining how to use that id (e.g., for management or unsubscribe). However, given the rich parameter details, prerequisites, and delivery semantics, the description is largely complete. The only notable gap is the lack of explicit guidance on using the returned id in downstream operations.

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

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

Input schema covers all 3 parameters with detailed descriptions, achieving 100% coverage (baseline 3). The description adds value with concrete examples and domain explanations, such as 'items:["5.02"] = officer change' and 'Polymarket↔Kalshi cross-venue mispricings', which clarify the intended usage beyond the schema. It also reiterates constraints like the 10/day cap and phone matching, reinforcing but not completely duplicating the schema.

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

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

The description clearly states the verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also specifies the return value (new subscription id) and distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation. The supported types and delivery channels are enumerated, providing a specific and comprehensive 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?

The description gives strong contextual usage guidance, including the requirement for a Pipeworx OAuth account and explicit caveats for anonymous/BYO users. It explains the delivery channels and how to consume the feed via recent_alerts, but it does not explicitly compare to alternative tools or state when not to use this tool (e.g., for one-time data fetching). Thus it has clear context but lacks explicit 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable behavioral detail: it returns category-bucketed example questions, each with the exact tool and argument shape, drawn from a live catalog of thousands of tools. It also explains the optional topic focus 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?

The description is somewhat long due to the initial list of example user phrasings, but this list is useful for intent matching. The core purpose, behavior, and usage are clearly stated in structured sentences that follow the front-loaded examples. Every part serves a purpose, though it could be trimmed 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?

Despite having no output schema, the description fully explains what the tool returns: category-bucketed example questions with tool and argument shape. It also covers the parameters, use cases, and relationship to meta-tools. The annotations handle safety context, making the description complete for an agent to invoke the tool confidently.

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 describes the single optional 'topic' parameter with a list of values and meaning, providing 100% coverage. The description adds further context by giving examples ('finance', 'pharma', 'betting') and clarifying that omitting the parameter yields a cross-category spread. This reinforces and slightly extends 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 identifies the tool as an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape for each. It uses a specific verb ('suggest') and resource ('Pipeworx capabilities'), and distinguishes from siblings by positioning itself as the 'first' step for learning what to ask and how to call meta-tools.

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

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

It gives explicit guidance to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains the no-argument vs. topic-argument options. However, it does not explicitly state when not to use it or name alternative tools like discover_tools, though it references meta-tools as related.

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 meaningful behavior beyond the annotations: ownership enforcement (auth), soft-delete vs hard-delete, and a pointer to recent_alerts for historical events. This aligns with annotations (destructiveHint=false, idempotentHint=true) while enriching them.

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

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

The description is two concise sentences, front-loaded with the primary purpose, and every clause adds value (ownership, deactivation, historical availability). No wasted words.

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

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

For a simple one-parameter cancellation tool with strong annotations and no output schema, the description covers purpose, side effects, ownership, and related tool behavior. It is complete and self-contained.

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

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

The schema already fully describes the single parameter 'id' as 'Subscription id (uuid) returned by subscribe'. The description only says 'by id', adding no new semantic information, so the baseline 3 applies.

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

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

The description states 'Cancel a subscription by id' with a clear verb and object, and further clarifies the deactivation behavior. This distinguishes it from sibling tools like subscribe and list_subscriptions by focusing specifically on cancellation.

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

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

It provides clear context: ownership is enforced, and cancellation deactivates rather than deletes. It implies the tool is for canceling your own subscriptions, but does not explicitly name alternatives (e.g., list_subscriptions for viewing).

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?

Even though annotations already declare readOnly/openWorld/idempotent, the description adds substantial behavioral detail beyond annotations: it explains the two fallback paths, the meaning of each verdict (especially that 'could_not_verify' does not count as evidence), the inclusion of a verification_error object with stage/detail, and the tolerance_pct override behavior. This goes well beyond the structured annotations.

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

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

The description is long, but every sentence contributes useful information: examples, routing logic, verdict meanings, error semantics, and integration notes. It is well-structured, starting with usage examples then flowing into technical behavior. It earns its length for a complex tool, though a slightly tighter organization could improve scannability.

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

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

With no output schema, the description adequately covers return values (verdict, actual value with citation, reasoning) and error behavior (verification_error, could_not_verify semantics). It also addresses the source routing context and the tolerance override. The tool's complexity is fully matched by the description, leaving no major gaps for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. For 'claim' it provides concrete natural-language examples. For 'tolerance_pct' it explains the numeric range, the default behavior (implied by wording, capped at 5), and a concrete use case (hallucination detection with 1–2). This enriches parameter understanding for correct invocation.

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

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

The description clearly identifies the tool's purpose with verbs like 'verify', 'confirm or refute', and 'fact check', targeting natural-language claim verification. It distinguishes itself from siblings by describing two routing paths (SEC EDGAR/XBRL fast path and grounded pipeline) and by noting it replaces 4–6 sequential calls, which is unique among likely similar tools like get_fact or get_facts.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives clear guidance on interpreting results, especially the critical distinction between 'could_not_verify' and 'unsupported'. However, it does not explicitly mention alternatives or when not to use it, though the mention of replacing sequential calls implies a consolidation benefit.

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