zippopotam

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavior: it explains the free default model (Workers AI Llama-3.3-70b), the BYO-key mechanism for Anthropic with direct cost implications, and the return structure {score, confidence, signals, raw_response} + combined view. No contradiction with annotations. It adds context beyond annotations without over-explaining.

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

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

The description is three sentences, front-loaded with the primary purpose, then details the default model/optional key, then the return format and use cases. Every sentence adds necessary information with no filler or repetition.

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 moderate complexity (4 params, no output schema), the description covers the essential aspects: what it does, how to configure models, return format, and typical use cases. It lacks minor details like rate limits or score computation methodology, but these are not critical for selecting/invoking the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some extra context by explaining that the default model is free and that _apiKey is for Anthropic, but it largely reiterates what the schema already states (e.g., _apiKey is 'Optional Anthropic API key'). No major enrichment beyond schema descriptions.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This precisely states the tool's purpose and differentiates it from siblings like ask_pipeworx or deep_research by focusing on visibility scoring across models. The mention of per-model scoring and a combined view further clarifies its unique role.

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

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

The description provides clear use contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly state when not to use it or name alternative tools for similar tasks, so it stops short of the 'explicit when/when-not' level.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the description adds useful non-obvious context: internal routing to one of thousands of tools, automatic argument filling, stable pipeworx:// citation URIs, and compatibility with every tier. It also notes that it routes to live news feeds. Slightly more detail on failure or rate-limit behavior would push this to 5, but there is 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 long, but it is front-loaded with the highest-priority instruction ('PREFER OVER WEB SEARCH') and is organized from broad scope to trigger phrases to examples to escalation paths. There is some redundancy, such as repeating the 'use whenever' guidance after already listing examples, but each section earns its place by supporting routing decisions.

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

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

The description covers domain breadth, example inputs, return behavior (structured answer with stable pipeworx:// citation URIs), and explicit escalation rules to sibling tools. Since there is no output schema and the tool is a broad router, this is nearly complete; a little more detail about response shape or error handling would be needed for a 5.

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

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

The schema already documents all six parameters at 100% coverage, all as aliases for `question`, so the baseline is 3. The description adds meaning by specifying the kinds of natural-language prompts that work (SEC filings, FDA drugs, FRED statistics, patents, real estate, weather, clinical trials, etc.) and by giving realistic example questions. This materially helps an agent formulate the `question` argument even though no additional syntax is needed.

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

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

Description states a very specific role: routes factual/current-data questions to one of 5,743 tools across 1,500 sources and returns structured answers with citation URIs. It distinguishes itself from ask_pipeworx_grounded and deep_research by naming exactly when each should be used, and it gives concrete domains and example queries. This is a clear, differentiated purpose statement.

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

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

Explicitly instructs agents to prefer this tool over web search for factual questions, provides trigger phrases like 'what is', 'look up', 'find', and 'get the latest', and says 'START HERE'. It gives explicit escalation conditions for ask_pipeworx_grounded and deep_research, and clarifies that breaking-news questions are also handled by this tool. This removes ambiguity about when to select it 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?

The description discloses rich behavioral context beyond the annotations: experimental status, the fact that no candidate is currently active (last retired 2026-07-26), that it currently matches ask_pipeworx exactly, and that it 'falls back to nothing' but is a full working router. This complements the readOnly/idempotent hints without 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 front-loaded with the essential beta/equivalence information and explains the current state and purpose in three sentences. There is minor redundancy between 'No candidate is active right now' and 'this currently matches ask_pipeworx exactly,' but no wasted words overall.

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 question-routing tool with no output schema, the description states that the response shape is identical to ask_pipeworx, which provides enough grounding given that ask_pipeworx is a sibling tool. It also clarifies the experimental context. It does not spell out the exact return format, but the reference to the stable counterpart is adequate.

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

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

Schema coverage is 100% and all parameters are documented as aliases for question. The description adds only the phrase 'same arguments' and 'same response shape,' contributing little beyond the schema. 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 identifies the tool as the beta version of ask_pipeworx, a universal router with identical toolset, arguments, and response shape. It clearly distinguishes this from the stable ask_pipeworx by noting it carries candidate routing improvements when under test.

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

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

It explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router to decide what merges. However, it does not provide explicit exclusion conditions or mention ask_pipeworx_grounded as an alternative.

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

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

The description reveals key behaviors beyond the annotations: it only uses the tool result, can return explicit refusals with detailed reasons, and costs an extra LLM call relative to ask_pipeworx. It does not contradict the readOnlyHint, openWorldHint, or idempotentHint 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 earns its place: purpose, routing, extraction behavior, return contract, refusal reasons, usage guidance, and cost tradeoff. The most important scoping statement is front-loaded.

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

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

Even without an output schema, the description defines the full success/refusal response shapes and enumerates all refusal_reason values. Combined with the annotations and schema, an agent has everything needed to decide when and how to 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?

Schema coverage is 100%, with all six parameters documented as aliases for 'question'. The description adds no additional parameter-level meaning, but it doesn't need to because the schema already fully explains the single semantic 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 states a clear, specific purpose: a hallucination-resistant variant that extracts answers only from tool results, explicitly contrasting itself with ask_pipeworx. This differentiates it from the sibling tool without requiring schema inspection.

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

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

It gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on and facts must not be invented. It also names the alternative (ask_pipeworx) and says to prefer that for casual lookups due to the extra LLM call.

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?

Goes far beyond the annotations (readOnlyHint=true, idempotentHint=true). It discloses resolver contract behavior (market_match_confidence, alternatives, suggestions), safety short-circuits (low_confidence_match, market_closed_or_inactive), fan-out parallelism, tradeability flags, and resolution-rule risk with ev_impact. The description fully maps operational behavior that annotations cannot capture.

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

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

Despite being long, the description is densely informative and well-structured with uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). The core purpose is front-loaded, and every section provides unique operational guidance without redundancy.

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

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

No output schema exists, so the description carries full responsibility for explaining return values. It details result shapes (result.market, result.analysis, result.evidence), status paths, safety mechanisms, news fallback fields, and cancellation-rule parsing. It thoroughly covers edge cases like de-indexed markets and GDELT 429s, making it 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?

Schema description coverage is 100%, so baseline is 3. The description repeats market input formats (slug, URL, question text) that already appear in the schema, and it does not add additional nuance for depth or include_raw beyond what the schema provides. No extra parameter meaning is contributed.

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 combination: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This clearly distinguishes it from sibling tools like ask_pipeworx or deep_research by focusing on betting-specific evidence with fan-out. Concrete usage examples ('should I bet on X') reinforce the 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 provides an explicit 'Use for' list: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It states clear contexts for invocation. However, it does not name alternatives or exclusion criteria (e.g., when to use ask_pipeworx instead), so it falls short of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description goes beyond them: it reveals that company data comes from SEC EDGAR/XBRL with correct off-calendar fiscal year handling, that results are sorted by the primary metric, and that output includes paired data plus citation URIs. No contradictions with annotations.

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

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

The description is dense but every sentence earns its place: trigger phrases, preference instruction, type-specific data sources, fiscal-year handling, sorting behavior, and return format. It is front-loaded with usage intent and contains 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?

Even without an output schema, the description fully specifies return contents (paired data + pipeworx:// citation URIs), result ordering, and per-type data sources. For a two-parameter comparison tool, it covers all necessary operational context.

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

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

Schema coverage is 100%, but the description enriches both parameters: 'type' is explained with what data each enum value pulls (10-K financials vs FAERS/trial counts), and 'values' is clarified with examples like tickers ([AAPL, MSFT]) and drug names ([ozempic, mounjaro]). This adds meaning beyond the bare schema definitions.

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

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

The description opens with concrete trigger phrases ('Compare X and Y', 'X vs Y', 'which is bigger') and clearly states the tool's function: side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes itself from sibling tools by explicitly naming the alternative ('sequential single-pack lookups') and detailing the exact data sources per entity type.

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

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

The description explicitly instructs agents to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear usage guidance. It also explains the two modes (company vs drug) and gives example queries, making it obvious when to invoke this tool 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 carry readOnly/openWorld/idempotent hints, but the description adds substantial behavior: account/paywall requirements, parallel decomposition across 5,743 tools, gaps[] and contradictions[], citation_uri fetchability, semantic excerpting, and latency expectations. It clarifies the 'open world' hint by stating data sources are structured, not arbitrary web search.

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

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

The description is long but front-loaded with the critical account constraint, and nearly every sentence adds unique value. Its dense single-paragraph format is somewhat taxing, but the complexity of the tool justifies most of the length.

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

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

With no output schema, the description fully carries the burden of explaining return semantics: findings with verbatim evidence, confidence, source, fetched_at, stable citations, gaps[], contradictions[], and hop/citation_uri fields. It also covers account prerequisites, exclusions, and timing, leaving little for an 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?

Schema description coverage is 100%, so the baseline is 3, but the description meaningfully enriches the depth parameter by explaining 'standard' gap-recovery and 'thorough' lead-chasing behavior, and clarifies that broad/multi-part questions are welcome. This goes beyond the enum 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?

States a specific verb ('research') and a precise resource ('Pipeworx's 1500 STRUCTURED data sources'), and explicitly differentiates from open-web search and from ask_pipeworx. The 'NOT open-web search' phrasing makes the tool's identity unmistakable.

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 when-to-use and when-not-to-use guidance: use for broad/multi-part structured-data research, use ask_pipeworx for single lookups or breaking/current news, and use ask_pipeworx if not signed in. The description even names alternatives with conditions.

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 the tool as read-only and idempotent. The description adds useful behavioral context beyond this, such as returning top-N tools with full schemas and curated examples, and that no second schema lookup is needed. This gives the agent a clear expectation of the tool's output behavior.

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

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

The description is succinct and front-loaded with the core purpose. The long domain list is informative rather than wasteful, and the additional sentences about return behavior and when to call it earn their place. It is not overly verbose.

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 discovery tool with no output schema, the description thoroughly explains what is returned (top-N tools with names, descriptions, full input schemas), that results are directly callable, and when to use the tool. It also covers the input style ('describing the data or task'). This is complete for the tool's complexity.

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

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

Schema description coverage is 100%, with all six parameters documented, including aliases and the default/max values for limit. The description's mention of 'top-N' reinforces the limit concept but does not add much beyond what the schema already provides. The baseline score of 3 is appropriate here.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It clearly distinguishes this tool from siblings by positioning it as the tool-discovery entry point, especially with 'Call this FIRST when you have many tools available.' The scope is explicit and unambiguous.

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

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

The description provides clear when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also gives an exclusion ('not just one answer'), though it does not explicitly name 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 mark the tool read-only, open-world, and idempotent, and the description adds substantial behavioral context: it fans out across multiple sources, soft-fails USPTO patents after May 2025, reports fda_products as 'expected, not a failure' when empty, and explains that sources_used/sources_failed distinguish real no-data from bugs. No contradiction with annotations exists.

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

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

The description is long but densely packed with necessary detail for a complex tool that has no output schema. It is front-loaded with user intents and the key routing directive, and it groups related behavior (data sources, returns, failure semantics) logically. There is minor redundancy around accepted input forms, but overall every sentence 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?

Given that there is no output schema, the description is unusually complete: it enumerates every return section (cik, recent_filings with URIs, fundamentals, patents, contracts, FDA products, hiring, news, LEI, sources_used/sources_failed), explains failure/empty semantics, and covers edge cases like private companies and interchangeable type values. An agent has enough to invoke the tool correctly without additional context.

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

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

Schema coverage is 100%, but the description goes well beyond it: it explains that 'company' and 'ticker' behave identically, gives concrete examples for ticker/CIK/name, notes zero-padding requirements, and describes name resolution via SEC EDGAR plus the resolved_from/resolved_to behavior. This materially helps an agent construct correct values.

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

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

The description uses a specific verb ('returns a full cross-source profile') and clearly names the resource ('US public company'), and it opens with concrete user intents. It also distinguishes itself from 'chaining single-pack SEC/XBRL/news lookups' and lists exactly what sections are returned, so an agent can tell it apart from siblings like compare_entities or resolve_entity.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which directly answers when to use this tool versus alternatives. It also clarifies expected input forms and states that private companies return resolved:false rather than failing, giving the agent clear routing and fallback 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?

Description states what is destroyed (a previously stored memory) and implies permanence with 'delete'. Annotations provide destructiveHint=true and idempotentHint=true, so the description adds contextual context about clearing sensitive data beyond the annotations.

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

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

Two concise, front-loaded sentences that cover purpose, usage, and complementary tools without fluff.

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

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

For a simple one-parameter tool with good annotations, the description fully covers when and why to use it. No output schema exists, but no return value explanation is needed.

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

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

The schema already describes the single parameter `key` as 'Memory key to delete' at 100% coverage. The description adds no additional 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?

Clearly states the tool deletes a previously stored memory by key. Uses the verb 'delete' and specifies the resource, distinguishing it from sibling memory tools like remember and recall.

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

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

Provides explicit use cases: stale context, completed task, clearing sensitive data. Mentions pairing with remember and recall, showing integration, though it doesn't explicitly specify when not to use it.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds useful process context: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. 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 sentences, front-loaded with the primary action, and each sentence contributes value (what it does, how it does it, use cases). No filler or repetition.

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 complete schema and safety annotations, the description covers output format (standard llms.txt, single text blob) and use cases. The tool is simple enough that no further details are needed.

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

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

Schema has 100% coverage for both parameters, and the description adds no additional parameter-specific meaning beyond what the schema already provides. Baseline 3 is appropriate due to full schema coverage.

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

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

Specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. Distinguishes from siblings by mentioning AI crawler indexing and auditing competitor visibility, which differentiates from tools like scan_competitor_ai_presence.

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

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

Provides explicit 'Useful for:' scenarios (client indexing, own project, competitor audit), but does not name alternative sibling tools or state when not to use this tool. The context is clear 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral details: it returns specific fields, defaults to active subscriptions, and supports including cancelled ones via the include_inactive parameter. 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?

Two concise sentences: the first states the action and return fields, the second explains when to use the tool. Every sentence earns its place, with no redundancy or filler. Excellent structure.

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 listing tool with one optional parameter, the description is largely complete. It lists the return fields, notes the default filter, and provides usage context. It is slightly lacking in explaining the format of the 'params' field and any pagination, but those are minor given the low complexity.

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

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

The schema has 100% description coverage for the only parameter (include_inactive), which is already explained in the schema. The description mentions 'active' vs 'inactive' but does not add meaningful syntax or semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists 'the caller's active subscriptions' with a specific verb ('List') and resource ('subscriptions'), and even enumerates the returned fields. This distinguishes it from sibling tools like subscribe and unsubscribe, which are mutation tools.

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

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

The description provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This offers clear contextual guidance, though it does not mention alternatives or when not to use the tool, so a 4 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect profile. The description adds input flexibility (names or codes) but does not disclose additional behavioral traits like rate limits, pagination, or error handling. Given the strong annotation coverage, the description provides some value but not substantial behavioral context, warranting a baseline 3.

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, efficient sentence that immediately states the tool's purpose and includes valuable input flexibility examples. It is front-loaded with the verb and resource, and every phrase earns its place. No fluff or redundant details.

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

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

For a simple read-only lookup tool with a comprehensive input schema and an output schema, the description is complete enough. It clearly indicates required inputs, provides formatting examples, and the annotations cover safety and idempotency. There are no missing critical details for selecting and invoking the tool correctly.

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

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

The input schema has 100% description coverage with detailed descriptions for each parameter (e.g., state: 'by name or abbreviation'), and the description includes examples like 'California'/'CA' and 'United States'/'US'. However, the description largely reiterates what the schema already states, adding no new semantic meaning beyond the schema. Thus, the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'Get all postal codes (ZIP codes) for a city, given its country and state or province.' It uses a specific verb ('get') and resource ('postal codes'), but does not explicitly differentiate from the sibling tool 'lookup_zipcode', which might be the reverse operation. Therefore, it meets the criteria for a clear purpose without 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?

The description implies when to use the tool (when you need postal codes for a city given country and state), and provides input flexibility guidance ('Country and state may be written as names or codes'). However, it does not mention alternatives or when not to use this tool, such as pointing to 'lookup_zipcode' for the reverse lookup. Thus, usage context is implied but no explicit exclusions or alternatives are given.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds valuable operational context: 'Free, sub-second, no auth' and the 60+ country coverage, which go beyond the structured annotations. No contradiction with annotations exists.

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

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

Three sentences, each earning its place: the first states core purposes, the second gives targeted usage guidance, and the third provides operational facts. The description is front-loaded with the key verb and avoids any filler, making it highly efficient.

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

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

For a simple two-parameter lookup with an output schema, the description covers purpose, usage context, geographical scope, performance, and auth requirements. It is complete enough for an agent to select and invoke the tool correctly without additional information.

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

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

Input schema coverage is 100% with both parameters clearly described (ISO 3166-1 alpha-2 country code and ZIP/postal code). The description adds no new parameter-level details, but the schema fully carries that burden, so a 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 starts with the specific verb 'Resolve' and clearly states the input (ZIP/postal code) and outputs (city, state/province, latitude/longitude) for 60+ countries. This distinguishes the tool from siblings like lookup_city and web search by framing the exact reverse geocoding 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?

It explicitly says 'PREFER OVER WEB SEARCH' for specific query types and instructs to use it as the first step in geo-aware workflows, even naming downstream examples like weather and attom. This provides clear when-to-use guidance and an explicit exclusion of web search.

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 only provide negative hints (all false), so the description carries the burden. It discloses that anonymous filing returns a claim_token, how to pass it back later to check status, rate-limiting (5 per identifier per day), free/quota-exempt status, and the team's daily digest review. It also warns not to paste end-user prompts, adding a behavioral boundary beyond annotations.

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

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

The description is dense and front-loaded with the core purpose. Every sentence earns its place (usage, exclusions, token flow, rate limits, quota). It's longer than typical, but the complexity of the tool (anonymous token flow, policy boundaries) justifies it. No fluff, though a tighter structure could improve readability.

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

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

With no output schema, the description compensates by explaining the return behavior (claim_token), the follow-up mechanism, and the policy constraints (rate limit, quota exemption, daily digest). It also covers error-avoidance guidance (don't report non-Pipeworx tools). For a feedback tool, this is complete and self-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%, so baseline is 3. The description adds cross-parameter meaning: how claim_token is used in a follow-up call with no other arguments, and explicit guidance for the message parameter to 'describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This goes 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's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This is a specific verb (tell) + resource (Pipeworx team) + scope (broken/missing/existing). It distinguishes from sibling tools like ask_pipeworx, which are for querying, not reporting.

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

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

The description explicitly states when to use it: for bugs, feature requests, data gaps, or praise. It also provides exclusions and alternatives: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' This gives clear guidance and names 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 (readOnly, openWorld, idempotent, non-destructive), the description adds valuable behavioral details: the data source (CF analytics-engine), privacy (no PII), content (pack, tool, count), and caching behavior (5min-1h). This transparency helps set expectations for freshness and scope, exceeding what annotations alone 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 concise, front-loaded with the core purpose, and uses a structured list for use cases. Every sentence adds new information—from the aggregate signal nature to caching details—without fluff or redundancy.

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

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

The tool is simple (one optional parameter) and has strong annotations and schema coverage. The description covers the return structure (top tools, top packs, total call volume), the timing windows, and data provenance. Without an output schema, this is sufficient 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 schema already fully documents the single 'window' parameter with enum values and descriptions (including the hot-right-now vs steady-state trade-off). The tool description mentions the window options but adds no additional semantic value beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: showing what other AI agents are calling on Pipeworx, returning top tools, top packs, and total call volume. It uses specific verbs and outputs, and distinguishes itself from siblings like ask_pipeworx or discover_tools by focusing on aggregate signals from other agents.

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 three explicit use cases (discovering hot data sources, confirming canonical tools, seeing alignment with collective usage) and explains the trade-off between windows. It doesn't explicitly name alternative tools or say when not to use it, but the use cases give clear context for appropriate invocation.

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, open-world, idempotent, non-destructive. The description adds substantial behavior: Jaccard ≥0.30 threshold, >3pp deviation trigger, >20% placeholder filter, and the fill check distinction between theoretical vs realizable edge. 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 dense but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence carries operational weight; 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?

Given no output schema, the description fully documents the response structure and field names, plus edge cases and fallback behavior. It also references the fill risk tool for custom sizing, leaving no significant gap.

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 elevates the semantics by explaining how 'event' and 'topic' map to scan modes, giving examples of slugs, and detailing the different checks performed in each mode. It also reveals the no-arg behavior.

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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges or polymarket_fill_risk by focusing on arbitrage detection.

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 tells when to call with no args ('trending_scan'), when to pass 'event' vs 'topic', and recommends 'event' for specific markets. It also directs custom sizing to 'polymarket_fill_risk', naming an alternative.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), response segments (by_segment, fed_candidates, _diagnostics), and per-opportunity warnings ('Market moved X.Xpp in 24h'). It also explains why some segments may be empty via _diagnostics funnel counters.

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 (~300 words) but front-loaded with purpose and organized with bold section labels (FIVE MODEL FAMILIES, RESPONSE TOP-LEVEL, TRADEABLE-EDGE KNOBS). While not concise, the density is warranted by the tool's complexity; every section adds operational or interpretability value.

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

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

Given no output schema, the description fully explains top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers edge cases like Fed bet unreliability and placeholder-slug filters, making it sufficiently complete for correct invocation.

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

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

Schema covers 100% of 9 parameters with detailed descriptions. The description adds high-level grouping ('TRADEABLE-EDGE KNOBS') and explains the intent of min_liquidity/max_spread_pp and min_partition_leg_kelly beyond schema syntax, e.g., partition arbs always return kelly_fraction_half=0 at parent level. This supplemental context earns above baseline.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly differentiates from siblings like polymarket_arbitrage or polymarket_edge_tracker by highlighting the Pipeworx data disagreement and the 'what should I bet on today' use case.

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 clear context for when to use: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains what the tool returns and surfaces diagnostics for empty segments, but doesn't explicitly name alternative sibling tools or give when-not-to-use conditions.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses behavioral details: snapshot-based data collection, cache-miss writing behavior, 60-day TTL, daily close basis for decay numbers, and signed edge values. This gives the agent a full understanding of what the tool returns and its limitations.

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

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

Long but efficiently structured: purpose, args, response, limits in separate blocks. Each sentence adds functional value; no filler. The length is justified by the complexity of the response shape and edge cases.

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

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

For a complex tool with no output schema, the description provides a comprehensive breakdown of the response fields (tracked[], expired[], snapshot_dates[]), field semantics (trend, decay_pp_per_day, lifespan_days), and limitations (TTL, sampling). This fully compensates for the lack of an output schema.

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

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

Schema covers 100% of parameters, including defaults and valid ranges. The description restates 'days (lookback, default 14, max 30)' and 'window (snapshot family, default 1wk)' without adding new semantic meaning, so it doesn't elevate beyond the schema's thorough 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 the tool's function with a specific verb phrase ('Edge persistence and decay telemetry') and answers a concrete question ('how long has this edge existed and is it shrinking?'). It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series persistence rather than current edges.

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

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

Provides clear context for when to use: when you need to assess edge age and decay trends, framing the distinction between fresh and stale edges. It gives response interpretation guidance ('median lifespan is your competition clock') but does not explicitly exclude alternatives for scenarios like current edge discovery, though that is implied by the existence of siblings.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial context beyond annotations: it details what the tool calculates (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, capture_ratio, forced_directional_risk, etc.), how size_usd is interpreted in each mode, and the risk of partial basket fills converting an arb into 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 dense and well-structured, front-loading the core purpose and then alternating between single-market and basket details. It is fairly long but every sentence carries essential information given the tool's two modes and many return fields. It could be slightly more concise by eliminating minor repetition, but overall it is organized for readability.

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

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

Given the tool's complexity (two modes, multiple parameters, rich return values), the description is remarkably complete. It explains output fields, parameter semantics, usage timing, potential risks, and limitations. With no output schema, the description carries the burden of conveying what the tool returns, and it does so thoroughly.

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

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

Schema description coverage is 100% and the schema documents each parameter's basic role. The description adds significant meaning: it explains the two modes (`market` vs `event`), the default behavior of `side` in basket mode (auto based on partition sum), and the distinct interpretation of `size_usd` in single-market vs basket mode (spend/proceeds vs settlement notional per share). This exceeds 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 states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It uses a specific verb ('check') and resource ('CLOB order-book depth'), and distinguishes between single-market and basket modes. It also references sibling tools (polymarket_arbitrage, polymarket_edges) to position its unique role, making it easy to differentiate.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the context and rationale, including why theoretical overround on thin books is not capturable and how partial fills create unhedged directional risk. This clearly states when and why to use this tool over 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 mark this as readOnly/idempotent/non-destructive, but the description adds substantial behavior beyond that: response structure, safety fields, compatibility code semantics, fee disclosure, skipped-leg counting, and temporal alignment pitfalls. It explicitly discloses that the tool does not model Kalshi's fee schedule and that spreads are gross, not net — exactly the behavioral context an agent needs.

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

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

Although long, the description is well organized (purpose, modes, response, safety, fees, counters) and every section carries operational value. The core purpose is front-loaded, and the caveats are placed where they matter. There is no filler 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?

With no output schema, the description fully documents the returned structure (leg prices, spread[].top_spreads_pp, compatibility fields, skipped counters) and failure/safety semantics. It gives an agent everything needed to invoke the tool correctly and interpret results, without requiring an external schema.

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

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

The schema already describes each parameter, but the description enriches them significantly: it enumerates all 10 topic values, explains that explicit ticker/slug override the mapped side, and clarifies that both modes run the same matcher. This gives the agent the full semantic range and override behavior beyond the schema's terse examples.

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

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

States a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from sibling polymarket tools by framing the output as a matched spread with safety disclosures, and explicitly differentiates it from a tradeable arbitrage ('not a net tradeable edge'). The title and description align closely, and the description adds scope beyond the title.

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?

Describes two modes — topic shortcuts vs explicit ticker/slug pairing — and when each is appropriate. Warns that 'pre-mapped ≠ tradeable' and that most topics return a compatibility_warning, setting clear expectations. It doesn't explicitly name sibling alternatives like polymarket_arbitrage or polymarket_edges for comparison, so it provides clear context but lacks explicit exclusionary guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the baseline for extra value is lower. The description adds meaningful behavioral context beyond annotations: the tool is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID), and omitting the key lists all saved values. This clarifies data isolation and dual-mode behavior, though it does not cover return formats or error handling.

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

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

The description is three sentences, front-loaded with the main action and behavior. The second sentence illustrates use cases, and the third covers scoping and related tools. Every sentence contributes value with no redundancy or fluff, achieving excellent brevity for the information conveyed.

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 one optional parameter, no output schema, and annotations covering safety, the description is fully adequate. It explains the dual behavior (retrieve vs. list), scoping, and integration with remember/forget. Nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

The input schema already provides 100% coverage for the single parameter, describing the key as 'Memory key to retrieve (omit to list all keys).' The description reiterates the same semantic in prose without adding new parameter-level details. With full schema coverage, the baseline of 3 applies; the description adds no additional parameter semantics.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' This clearly distinguishes the tool from its siblings (remember, forget) by describing both retrieval modes. The added examples of stored context (ticker, address, research notes) reinforce the purpose without ambiguity.

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 identifies related tools for alternative operations: 'Pair with remember to save, forget to delete.' This provides clear contextual guidance and excludes the need for re-derivation, making usage intent unambiguous.

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

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

Beyond the read-only/idempotent annotations, the description discloses key behavioral details: each alert carries source, citation_uri, and raw payload; mark_read:true flips read state so subsequent calls return only newer events. It also openly notes the same feed is accessible at a public URL. 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 sentences, front-loaded purpose, no fluff. Every sentence earns its place: payload composition, filtering, mark_read behavior, polling suitability, and alternative URL.

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 tells the agent what the return items contain, how to filter, how mark_read changes subsequent calls, and mentions polling and an alternate REST endpoint. This is fully sufficient for a read-oriented tool with 5 optional parameters.

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 covers 100% of parameters, so baseline is 3. The description adds value by giving a concrete type example ('sec_8k'), clarifying since as an ISO timestamp with semantics, and explaining the side-effect of mark_read. This goes beyond the schema descriptions, hence a 4.

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

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

The description opens with 'Pull fired events from your subscription feed,' a specific verb+resource statement that clearly distinguishes this from siblings like list_subscriptions or recent_changes. It also specifies what each alert carries, making the purpose unambiguous.

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

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

The description provides solid usage context: explains filtering by type/since, mentions 'Polls work fine' to endorse polling, and offers an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly contrast with similar sibling tools (e.g., recent_changes) or state when not to use it, so it falls short of full 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 readOnlyHint and idempotentHint annotations, the description discloses important behavioral details: it fans out to multiple sources (SEC, GDELT/GNews, USPTO), explains fallback logic (GDELT preferred, GNews when rate-limited or 5xx), and mentions USPTO soft-failure due to API sunset. This context is not available from annotations alone and sets accurate expectations for reliability and output.

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 the simplest examples but each sentence earns its place: it starts with the core purpose, then details the multi-source fan-out and failure modes, parameter usage, return shape, and alternative tool. The structure is logical and front-loaded, though slightly dense, so a 4 is appropriate.

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

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

Given the complexity of the tool (multiple external APIs, fallbacks, failure modes) and the absence of an output schema, the description adequately explains what is returned ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs') and covers the main behavioral edge cases. It is complete enough for an agent to select and invoke the tool correctly.

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

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

The schema already provides 100% coverage for all three parameters. The description enriches these by adding guidance like "Use '30d' or '1m' for typical monitoring," clarifying relative shorthand formats, and explaining how the value parameter maps to ticker or CIK. This goes beyond the schema's baseline and helps the agent choose good parameter values.

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

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

The description clearly states the function as a 'change feed for a company in the last N days/weeks/months' and provides example queries. It distinguishes itself from the sibling tool entity_profile by explicitly directing users to that tool for static profile needs, leaving no ambiguity about scope.

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

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

The description gives explicit when-to-use context with natural language examples like "what's new with X" and "updates on Acme." It also names an alternative (entity_profile) for cases where a static profile is needed, providing a clear decision rule.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: key-value storage scoped by identifier, persistence differences (authenticated vs anonymous 24-hour retention), and pairing with recall/forget. No contradictions with annotations.

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

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

Three concise sentences, front-loaded with the core purpose. Every sentence contributes—use case, storage mechanism, persistence, and complementary tools. 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 simple tool with two parameters and no output schema, the description covers purpose, usage, persistence behavior, scoping, and related operations. An agent has all necessary information to decide when and how to invoke it correctly.

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

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

Schema covers 100% of parameters with descriptions and examples for key and value. The description reinforces these examples but does not add new parameter-level semantics (e.g., length limits, format constraints). Baseline of 3 applies given the high schema coverage.

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

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

The description clearly states the tool saves data the agent needs later, using the verb 'Save' and identifying the resource as reusable data. It naturally distinguishes itself from sibling tools like 'recall' (retrieves) and 'forget' (deletes) by focusing on the write operation. Concrete examples (resolved ticker, target address, user preference) add precision.

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: 'Use when you discover something worth carrying forward' and provides examples. It also directs to complementary tools: 'Pair with recall to retrieve later, forget to delete,' making the choice vs alternatives 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?

Even with readOnly, openWorld, and idempotent annotations already present, the description discloses significant extra behavior: internal cascading lookups, graceful degradation when GLEIF or OpenFIGI is unavailable, returning figi_candidates instead of asserting on ambiguity, and explicitly labeling unresolved identifiers. This is substantial value beyond the annotations.

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

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

The core purpose and usage directive are front-loaded, and much of the detail is necessary for a complex tool. However, the company-type section is a very dense block of parenthetical caveats that could be restructured for easier scanning, so it is very good rather than maximally 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 compensates by explaining what identifiers will be returned, how ambiguous names are handled, what appears under unresolved, and what happens when enrichment sources fail. Together with the strong parameter guidance, an agent has enough information to call the tool correctly across the described cases.

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

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

Although schema coverage is 100%, the description adds meaning the schema alone does not convey: accepted input formats (ticker, CIK, ISIN, name), the warning to pass only the entity name and never the full noun phrase, and operational explanations of the type enum. It also gives examples like 'ozempic' that clarify how value should be formatted.

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 the specific verb 'resolve' and the object ('user-spoken NAME' to 'canonical/official identifiers'), and it opens with concrete example queries that make the purpose instantly recognizable. It also differentiates from siblings by framing the output as inputs other tools require, and it disambiguates from tools like lookup_city or lookup_zipcode by covering entity types rather than geographies.

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 an explicit routing rule: 'Use FIRST whenever you have a name but need an ID.' It also gives substantial context about supported types, input forms, and edge cases like bonds and ambiguous matches. It does not explicitly name alternative sibling tools or state when not to use it, so it falls just short of full exclusion guidance.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond these: it explicitly states it probes with ai_visibility_check, ranks by score, and returns a list with score, confidence, and signal density per entity. This explains the internal orchestration and output shape, exceeding the annotation 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?

The description is three sentences, front-loaded with the core purpose, followed by the mechanism and a concrete use case example. Every sentence adds value: the first defines the operation, the second explains the underlying call, and the third illustrates applicability and return structure. 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 the tool's moderate complexity (4 params, no output schema) and strong annotations, the description sufficiently covers what it does, how it works, and what it returns. It explicitly states the output includes ranking, score, confidence, and signal density, compensating for the missing output schema. The use case example also aids understanding.

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 of 3 is appropriate. The description does not add parameter-specific details beyond the schema; the schema already documents the entities array (first is subject, rest competitors), models, _apiKey, and context. The description's mention of 'your brand + N competitors' reinforces but does not extend the schema.

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

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

The description clearly states the tool's function: compare AI visibility across multiple entities side-by-side. It uses a specific verb ('probes'), identifies the resource ('each entity'), and distinguishes itself from the sibling tool ai_visibility_check by emphasizing multi-entity comparison and ranking. The purpose is unmistakable.

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

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

The description implies when to use this tool: for competitive AI-marketing audits, comparing multiple entities. It clearly indicates it wraps ai_visibility_check for multiple probes and returns a ranked comparison. However, it lacks explicit exclusions or alternatives (e.g., 'use ai_visibility_check for single-entity checks'), so it falls short of a 5.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing composite fan-out behavior, partial failure degradation ('Partial failures degrade gracefully'), a 5-30s latency on first bundlephobia measurement, and the meaning of 'sources_failed'. It also clarifies the return shape and ecosystem scope, adding significant context 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?

Four dense sentences deliver purpose, use cases, return fields, ecosystem limitations, and failure behavior. Every sentence adds value and the most critical information is front-loaded in the first sentence. No filler or repetition.

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 composite complexity and absence of an output schema, the description compensates exceptionally well. It enumerates the summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), mentions per-advisory detail, links, alternative versions, and explains timeout behavior. This is a complete picture for an agent to invoke and interpret results.

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

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

The input schema already documents both params fully with descriptions (package name, scoped packages accepted; version defaults to latest). The description does not add meaningful new semantic detail about the parameters themselves, so the schema coverage baseline of 3 applies.

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

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

The description opens with a specific composite purpose: 'Composite "should I add this npm package to my project" check in ONE call' and names the two underlying services (deps.dev, bundlephobia). It clearly distinguishes itself from sibling tools by being the only dependency-focused scanner, and lists exactly what it returns.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives a clear exclusion rule: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which directs users to an alternative for non-npm ecosystems.

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 substantial behavioral details beyond the annotations: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and has a 200K char cap with truncation and flagging. This provides rich context beyond 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 well-structured and front-loaded: the opening sentence gives the core purpose, followed by usage guidance, then technical specifics. Every sentence earns its place—no fluff, and it remains informative 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 lack of output schema, the description is remarkably complete. It explains the return format (passages with offsets and similarity scores), the algorithm, the input cap and truncation behavior, and how to integrate with a sibling tool. This covers all essential aspects for an agent to use 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?

Although the schema already describes all parameters (100% coverage), the description adds meaningful context: it explains the 'text' parameter as 'the text you already pulled' with examples, gives concrete query examples, and clarifies that 'limit' controls 'top-N passages' with default 5. This enhances the schema definitions.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record,' with a specific verb (search) and resource (record). It distinguishes from siblings by emphasizing the 'inside' scope and explicitly pairing with ask_pipeworx_grounded, making its purpose unmistakable.

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

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

Explicit guidance is given: 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This clearly states when to use it and how it relates to an alternative.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true), the description discloses critical behaviors: subscriptions are persistent, webhook signing secret returned only once, auto-disable after 10 consecutive failures, and auth requirements. These are actionable details not derivable from 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 longer than ideal, but every sentence carries useful content. It is front-loaded with the core purpose, then organized by type and delivery channel. A slightly more compact structure would improve, but the density justifies the length.

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

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

Given three parameters with nested objects and no output schema, the description is remarkably complete. It covers supported subscription types, param syntax, delivery options, authentication prerequisites, and edge cases (webhook secret, SMS verification, failure auto-disable). The agent has enough 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?

The schema covers all parameters with descriptions, but the tool description enriches them with concrete examples for each type (sec_8k, polymarket_edge, fred_series, etc.) and explains the delivery object's fields in depth, including verification and signing. This goes far beyond the schema's bare definitions.

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

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

The description starts with a specific verb 'Create' and clearly states the resource: 'proactive monitoring subscription to a live-data event stream.' It also mentions the return value (subscription id) and distinguishes from siblings like list_subscriptions and unsubscribe by describing the creation action.

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

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

Provides explicit prerequisites (OAuth account) and exclusions (anonymous + BYO cannot persist). Details delivery channels and per-channel constraints (SMS verified phone, 10/day cap), helping the agent decide when to use this tool and how to configure it. Sibling tools like list_subscriptions and unsubscribe are implicitly contrasted.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds context about the live catalog and output shape, but does not disclose additional behavioral traits such as rate limits, pagination, or side effects, which are not relevant for a read-only tool.

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

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

The description is comprehensive and well-structured, front-loaded with example queries and clear sections for purpose, output, usage, and when-to-use. It is somewhat verbose but every part earns its place, fitting the tool's onboarding role.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers what it does, how to call it, what it returns, and when to use it. It also provides enough context about the output shape (category-bucketed questions with tool+argument shape) and the meta-tools, making it self-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% with the 'topic' parameter fully described (allowed values and omit behavior). The description merely repeats examples ('finance', 'pharma', 'betting') that are already in the schema, adding no new semantic meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool and argument shape, positioning it as the onboarding entry point. It distinguishes itself from siblings by focusing on suggesting questions rather than answering them, and names specific 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?

Explicit guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and also when learning to call meta-tools. It explains when to call with no arguments vs. passing a topic, and mentions alternatives (meta-tools) by name.

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

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

Annotations already provide safety hints (readOnlyHint=false, destructiveHint=false, idempotentHint=true), but the description adds valuable behavioral detail beyond these: ownership enforcement and explicit deactivation rather than deletion. This directly explains the 'destructiveHint' and clarifies the tool's non-destructive nature, adding context that annotations alone do not convey. The description does not contradict any annotations.

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

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

The description is two sentences, front-loaded with the primary action, followed by concise behavioral context. Every sentence adds value with no redundancy. It is appropriately sized for a one-parameter tool.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete: it explains the action, the ownership constraint, the deactivation behavior, and the impact on historical events via recent_alerts. Combined with rich annotations, the agent has all necessary context to select and invoke the tool correctly.

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

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

The input schema already provides a clear description for the 'id' parameter ('Subscription id (uuid) returned by subscribe.'), achieving 100% schema description coverage. The description adds the ownership constraint ('you can only cancel your own subscriptions'), which is semantically relevant to the parameter and not present in the schema. This goes beyond the baseline 3 for full schema coverage.

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

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

The description opens with a clear verb+resource: 'Cancel a subscription by id.' It specifies the action, the target, and the input mechanism. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation and referencing subscription ownership.

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 indicates when to use this tool ('Cancel a subscription by id') and adds context that ownership is enforced (only your own subscriptions). It also explains the benefit of deactivation rather than deletion, implying use when history retention matters. It does not explicitly name alternative tools or list when-not-to-use scenarios, so it falls short of a 5.

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

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

Annotations already convey read-only, idempotent, non-destructive. The description adds substantial behavioral depth: the dual pipeline (SEC EDGAR structured vs grounded fallback), the full verdict enum, and the crucial caution that 'could_not_verify' is NOT evidence, carrying verification_error and must not be shown as supporting/refuting. This is exactly the kind of context annotations do not provide and no contradiction exists.

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

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

The description is longer than average but every sentence earns its place: scannable trigger phrases, a clear one-sentence definition, concise routing explanation, verbatim return payload summary, and a highlighted IMPORTANT caveat for error semantics. The structure is front-loaded and the 'IMPORTANT for callers' box draws attention to the critical edge case without 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?

Despite lacking an output schema, the description enumerates all possible verdict values, mentions the grounded actual value with citation, explains the meaning of 'could_not_verify' versus 'unsupported', and describes the integration benefit of replacing sequential calls. Given the tool's complexity, this is sufficiently complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, but the description goes far beyond the schema by explaining tolerance_pct semantics: 'Overrides the tolerance implied by the claim wording — set 1–2 for hallucination detection' and 'Default: implied by wording, capped at 5.' This transforms a bare numeric parameter into actionable guidance for different use cases.

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

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

The description opens with natural-language trigger phrases then states the verb+resource explicitly: 'natural-language claim verification against authoritative sources.' It clearly distinguishes from siblings like ask_pipeworx_grounded by defining a fact-check verdict output and the structured financial path for SEC EDGAR/XBRL.

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 'Use whenever the agent needs to check whether something a user said is factually correct' gives a clear when-to-use. It also explains the two routing paths (financial vs other) and notes it 'Replaces 4–6 sequential calls' to imply efficiency over alternatives, though it does not name specific sibling tools as exclusions.

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