Qrcode

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds important behavioral context beyond this: the default model is free Workers AI, while passing `_apiKey` triggers Anthropic calls and 'you pay Anthropic directly for those calls.' This external cost dependency is a valuable disclosure not captured by annotations.

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

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

Three sentences, each earning its place: core function, configuration nuance, and return format/use cases. Front-loaded with the primary action, 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?

The description covers the core function, configuration (default vs optional key), output shape (per-model + combined view), and use cases. With full parameter schema coverage and strong annotations, this is nearly complete for a read-only tool. It doesn't mention error handling or rate limits, but those are not critical given the tool's simplicity and annotation context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the default model when 'models' is omitted, and by clarifying that `_apiKey` is only needed for Anthropic and incurs direct costs. This cross-parameter context helps an agent reason about parameter selection and side effects.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses a specific verb ('probe') and resource ('LLMs'), and adds concrete output details (per-model score, confidence, signals, raw_response), making it distinct and non-tautological.

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 names use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains configuration prerequisites (pass `_apiKey` to probe Anthropic), providing clear context for when to use the tool. However, it doesn't explicitly compare with sibling tools or state when not to use it, 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?

The description adds behavioral context beyond annotations: it discloses that the tool routes to thousands of tools, returns stable citation URIs, works on every tier, and makes one fast call. It also hints at a limitation by recommending ask_pipeworx_grounded for hallucination-resistant answers, implying the base version is not fully grounded. Annotations already cover read-only/idempotent safety, so this is appropriate context.

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

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

The description is front-loaded with a strong directive and packed with actionable information, but it is somewhat lengthy and includes a long list of examples. Every sentence adds value, though conciseness could be improved by trimming redundant example categories.

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 adequately explains what is returned (structured answer with pipeworx:// citation URIs), when to use, when not to use, and provides examples. It is complete for a default entry-point tool of this complexity.

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

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

The schema description coverage is 100%, so the schema fully documents the question parameter and its aliases. The description adds examples of user queries but does not provide new parameter-level semantics beyond what the schema already contains. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: it routes questions to the appropriate one of 5,529 tools across verified sources and returns a structured answer with citation URIs. It also distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

The description explicitly tells when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to use alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It also provides concrete examples and a rule of thumb for common query phrasings.

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 traits. The description adds behavioral context: it is a full working router, not a fallback, with experimental routing improvements that can activate live, and currently matches ask_pipeworx exactly because no candidate is active.

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 beta identity. Each sentence adds non-redundant information about status, usage, and relationship to stable, though the specific date and repetition of 'router' add slight length.

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

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

For an experimental router variant, the description comprehensively covers identity, current behavior, usage, and comparison to stable ask_pipeworx. Without an output schema, referencing 'same response shape' sufficiently addresses return values.

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

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

The input schema has 100% coverage with descriptions for all parameters and aliases. The description merely says 'same arguments' without adding syntax or usage details, so it relies on the schema, earning the baseline score.

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

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

The description explicitly states this is the 'Beta version of ask_pipeworx: identical universal router' and specifies the same 5,529 tools, arguments, and response shape, clearly distinguishing it from the stable ask_pipeworx sibling.

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 direct usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This explicitly states when to use and implies the alternative is the stable router.

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), it discloses critical behaviors: explicit refusal reasons, the cost of an extra LLM call, and the strict grounding of answers in tool results. It even details the return shape and refusal payload, which is rich context not available in annotations.

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

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

The description is a single dense paragraph but every sentence provides essential information: purpose, routing, output, use cases, and cost trade-off. It is front-loaded with the core value proposition and avoids fluff, making it appropriately concise for its 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 compensates by explicitly describing both success and refusal return formats, including possible refusal reasons. It also covers usage context, routing behavior, and cost implications, making it fully complete for reliable tool selection and invocation.

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

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

The schema already covers all parameters (100% coverage) with clear descriptions and aliases, so the description does not need to elaborate. However, it adds no extra semantic guidance beyond what the schema provides, which is acceptable given the high 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 explicitly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and clearly distinguishes it from the sibling ask_pipeworx by emphasizing that it extracts answers only from tool results and returns evidence. It names the resource and behavior, making the 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?

It provides explicit guidance on when to use this tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'). It also names the sibling alternative directly, leaving no ambiguity about routing decisions.

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

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

The description goes far beyond the annotations by disclosing resolver confidence levels, short-circuit behavior for low-confidence matches, handling of closed/dead markets, illiquidity thresholds, news fallback details, and cancellation-rule risk. It provides extensive context about what happens under various conditions, making the tool's behavior highly predictable without contradicting the readOnly/idempotent/destructive hints.

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

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

The description is long but well-structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and each paragraph carries essential operational details. It front-loads the primary purpose and usage. While not concise in word count, every section earns its place for an agent needing to handle complex 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?

Given the tool's complexity, the description is remarkably complete. It explains input formats, classifier categories, fan-out logic, response structure (market, analysis, evidence), resolver contract, parent-event extraction, news fallback behavior, safety short-circuits, and resolution-rule risk. With no output schema present, the description bears full responsibility for explaining return values and 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?

The input schema already covers 100% of the parameters with descriptions for market, depth, and include_raw. The description reinforces these meanings but does not add substantial semantic detail beyond the schema—it mainly gives fan-out examples and response shape information, which are more about overall behavior than parameter semantics. 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 opens with a specific verb+resource+method: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clarifies the tool accepts slugs, URLs, or question text and distinguishes itself from sibling tools by focusing on per-bet research with a fan-out architecture. The purpose is unmistakable and unique among the listed siblings.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides classifier categories and fan-out examples that illustrate the appropriate domain. However, it does not explicitly mention when not to use it or name alternative tools, stopping short of the full exclusion/alternative guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral detail beyond that: it discloses data sources (SEC EDGAR/XBRL, FAERS, FDA), handles off-calendar fiscal years (AAPL, NVDA), sorts results by primary metric, and returns citation URIs. This gives the agent a clear picture of what happens during execution.

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 information-dense but well-structured: it starts with trigger phrases, then states the core function, then provides type-specific details, sorting behavior, and output format. Every sentence earns its place, with no redundant or filler content.

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

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

Given the tool's moderate complexity (two parameters, no output schema), the description covers key aspects: what it returns (paired data + citation URIs), how results are ordered, and what metrics are produced per type. It lacks explicit response structure details, but the description is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter meaning by explaining what each 'type' value retrieves (company: 10-K financial metrics; drug: FAERS counts, approvals, trials) and clarifies the 'values' parameter with examples. This goes beyond the bare enum/description in the schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with explicit trigger phrases ('X vs Y', 'which is bigger') and a distinct resource (companies/drugs). It distinguishes itself from siblings by emphasizing it replaces sequential lookups, making its purpose specific and non-overlapping.

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

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

The description gives explicit guidance on when to use the tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It names the alternative approach but does not explicitly exclude cases like single-entity lookups or mention a specific sibling tool as a fallback. Thus clear context with no explicit when-not exclusions.

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

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

Annotations already cover idempotency and non-destructive nature. The description adds that it returns an image URL ready to embed or download, which is useful behavioral context beyond the annotations. 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?

Two concise sentences, front-loaded with the action. Every word earns its place, with no redundancy or filler.

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

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

For a simple tool with only two parameters and 100% schema coverage, the description covers purpose, usage, and output format. The presence of an output schema further reduces the need to explain return values in detail.

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 provides 100% coverage for both parameters. The description confirms 'data' accepts text or URLs but adds no additional detail about the 'size' parameter beyond what the schema states. 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 generates a scannable QR code from text or URLs, distinguishing it from the sibling read_qr. The verb 'generate' and resource 'QR code' are specific 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?

Provides a direct 'Use when you need to encode information into a QR code' statement, which clearly indicates the intended use case. It does not explicitly mention alternatives like read_qr, but the context is sufficient for a simple tool.

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

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

Annotations already provide readOnly and idempotent hints, but the description goes far beyond by disclosing the decomposition strategy, the structure of the findings packet (verbatim evidence, confidence, source, fetched_at, citation), the gaps[] behavior with 'never invented', contradictions[], the hop field, and timing expectations. It also explains the difference between standard and thorough depth in terms of second-hop iteration. This is a rich behavioral contract.

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 deliberately dense, covering account requirements, alternatives, inner mechanics, output format, depth behaviors, and timing. It's front-loaded with the most critical constraint (account required) and each section earns its place. It could be trimmed slightly, but the complexity of the tool 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?

With no output schema, the description compensates by describing the return packet, citation_uri resolution, gaps[], contradictions[], semantic excerpting, and expected latency. It also covers edge cases (breaking news gives empty gaps) and prerequisites. Given the tool's complexity, the description is remarkably complete for selection and invocation.

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

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

Although schema coverage is 100%, the description adds meaning beyond the schema by explaining what each depth value does (quick=3 single hop, standard=5 adds gap recovery + contradictions, thorough=8 adds iterative chase) and by clarifying that the question parameter accepts broad/multi-part natural language. This extra semantics helps an agent reason about trade-offs and defaults.

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 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and clearly explains the core action: decomposing a question into facets and routing them to 5,529 tools in parallel. It also explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, which is a single lookup. The verb+resource+scope are specific 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?

Usage guidance is explicit and actionable: 'Best for broad/multi-part questions over structured data', and for single lookups or breaking news it directs the agent to prefer ask_pipeworx. It also notes account/prerequisite requirements, including the paid tier for 'thorough'. This is textbook when-to-use vs. alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral detail about outputs: it returns top-N tools with names, descriptions, and full schemas, and states each result is directly callable with no second lookup. This goes beyond the annotations without contradicting them.

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

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

Three sentences, front-loaded with purpose. The long domain list is purposeful because it signals the breadth of discoverable tools. Every sentence earns its place: purpose, usage context, return behavior, and first-step advice. No filler or redundancy.

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

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

This is a low-complexity discovery tool with no output schema. The description fully explains what the tool returns (top-N tools with schemas and examples), how the output is structured (ready to call directly), and when to invoke it. Given the strong input schema, no additional context is needed.

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

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

Schema coverage is 100%: all six parameters (query and its aliases, limit) have descriptions in the schema. The description's mention of 'top-N' adds some context for limit, but overall it doesn't significantly enhance what the schema already documents. 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 opens with a specific verb-resource pair ('Find tools by describing the data or task') and clarifies the tool's meta-purpose: browsing/discovering available tools. It also lists concrete domains (SEC filings, FDA drugs, FRED, etc.) and explicitly frames itself as the first-step discovery tool, which differentiates it from the many action-oriented sibling tools.

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

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

Clear when-to-use guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It stops short of explicit when-not-to-use or named alternatives, so it is not a full 5, but the context is strong.

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

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

Beyond annotations, it discloses fan-out behavior across SEC EDGAR, XBRL, USPTO, news, GLEIF, soft-fail patent behavior, GDELT→GNews fallback, and the exact return structure (cik, recent_filings, fundamentals, etc.). This is rich, non-obvious context that helps an agent predict outcomes.

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

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

The description is long but densely packed with valuable details: examples, fallbacks, return fields, and constraints. It is front-loaded with user intents and the core action, and every sentence adds operational value, though it could be slightly trimmed.

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

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

With no output schema, the description compensates by enumerating all returned components (cik + company_name, recent_filings, fundamentals, patents, news, LEI) and their behavior. It also covers edge cases like the USPTO API sunset and name-unsupported input, making it complete for an agent to invoke confidently.

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

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

The input schema already describes both parameters (type and value) at 100% coverage. The description adds example values ('AAPL', '0000320193') but no new parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It opens with concrete user intents ('Tell me about X') and distinguishes itself from chained single-source lookups, 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?

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides the alternative 'use resolve_entity first if you only have a name.' This gives strong when-to-use and when-not-to-use guidance.

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

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

Annotations already mark destructiveHint=true and idempotentHint=true. The description adds that it deletes by key and can clear sensitive data, adding context beyond the annotations. 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?

Two short sentences, front-loaded with the action. Every word earns its place.

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

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

With a single required parameter fully documented in schema, destructive/idempotent annotations, and clear usage guidance, the description is complete for this simple delete 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 covers the only parameter 'key' with description 'Memory key to delete' (100% coverage). The description merely restates 'by key' without adding new syntax or format details, so baseline 3 applies.

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

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

The description explicitly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes itself from siblings like remember and recall by focusing on deletion.

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

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

It provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data' and suggests pairing with remember and recall, covering 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 indicate readOnly and idempotent behavior, and the description adds process detail: it 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' plus that output is a text blob. This is meaningful context beyond the annotations.

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

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

The description is concise (two main sentences plus a short 'Useful for' list) and front-loaded with the primary action. Every clause adds value with no redundancy or fluff.

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

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

With simple parameters, strong annotations, and no output schema, the description fully covers what the tool does, its output format, and when to use it. It is complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, and the description does not add parameter-specific semantics beyond the schema. Baseline 3 is appropriate because the schema already documents all parameters.

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

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

The description states a specific verb+resource: 'Generate a production-ready llms.txt file for any URL.' It clearly distinguishes this from sibling tools by naming its unique output and format.

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

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

The description provides explicit use cases ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') but does not name alternatives or exclusions, so it gets a 4.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and the default behavior of excluding inactive subscriptions. This goes beyond the annotation safety profile and helps the agent understand what to expect.

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

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

Two sentences, front-loaded with the action and scope, followed by the return fields and a clear usage note. No wasted words; 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?

The description is complete for a simple list tool with one optional parameter. It explains the return fields, which is necessary since there is no output schema, and gives usage context. It does not mention pagination or ordering, but those are not critical for this tool's simplicity.

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

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

Schema description coverage is 100%, so the parameter include_inactive is fully documented in the schema. The description does not add any additional meaning about the parameter, 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 action ('List') and resource ('the caller's active subscriptions'), and specifies the return fields. It also distinguishes from sibling tools by adding the purpose of reviewing monitoring before adding more or finding an id to cancel, which implicitly contrasts with subscribe and unsubscribe.

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

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

The description provides clear context on when to use this tool ('Use this to review what you're monitoring before adding more or to find an id to cancel'). It does not explicitly name alternatives or exclusions, but the sibling names and context are sufficient for a simple list operation.

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

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

Annotations are all false (readOnlyHint, idempotentHint, etc.), so the description carries the full burden. It discloses the rate limit ('5 per identifier per day'), the free/no-quota behavior, the claim_token workflow (anonymous filing returns token; later pass it back to read resolution status), and the team's daily digest review. This goes far beyond what annotations provide.

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

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

The description is long but front-loaded with the core purpose. Every subsequent sentence adds critical operational detail (eligibility scope, claim token mechanics, rate limits). While it could be trimmed, the complexity of the tool justifies the length. The structure flows logically from purpose to use cases to exclusions to mechanics.

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

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

For a tool with complex behavior and no output schema, the description covers all necessary aspects: purpose, scope, exclusions, feedback type definitions, claim token lifecycle, rate limiting, and community impact. It even explains what happens after filing (token return, later status read) despite lacking an explicit output schema. This is fully complete for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning: it clarifies that claim_token is used for a separate read operation ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), that message should not include the end-user's prompt, and that context fields refer to Pipeworx-specific pack/tool/vertical identifiers. This enriches all parameters beyond their 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+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes the tool from all sibling tools by making clear it is for feedback about Pipeworx tools themselves, not for performing research or queries. The four feedback types (bug, feature, data_gap, praise) are explicitly listed.

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

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

The description provides explicit when-to-use criteria by mapping each feedback type to a concrete situation: 'wrong/stale data (bug), tool you wish existed (feature/data_gap), worked surprisingly well (praise).' It also gives a clear exclusion: feedback about non-Pipeworx MCP servers should be filed elsewhere. This is exemplary usage guidance with both positive and negative 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 declare read-only, open-world, idempotent, non-destructive. The description adds useful behavioral context: data source (CF analytics-engine), no PII, caching behavior, and output shape. This enriches beyond the annotations.

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

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

The description is appropriately sized, front-loaded with the core function, followed by use cases and technical context. Every sentence adds value, and the numbered use cases improve scannability.

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

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

Despite no output schema, the description explains the return values (top tools, packs, volume) and mentions caching, data source, and privacy. It is sufficient for a simple read-only tool with one parameter, though pagination details are not specified.

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 single 'window' parameter well-documented via enum and descriptions. The description reinforces the meaning but does not add significant new semantic detail beyond the schema.

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

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

The description clearly states the tool's purpose: shows what other AI agents are calling on Pipeworx, returning top tools, packs, and call volume. This specific verb+resource+scope distinguishes it from siblings like discover_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?

Provides three explicit use cases, explaining when to use the tool. However, it does not explicitly mention when not to use it or name alternative tools, but the guidance is clear and actionable.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds substantial behavioral context: the partition filter drops placeholder slugs, fill check prices against live CLOB depth, and warns 'realizable_edge_pp ≤ 0' means the edge is not tradable. It also mentions skipped_low_similarity as a rejection signal, enriching beyond annotation hints.

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

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

The description is lengthy but well-structured with clear mode sections and technical labels. It is front-loaded with the main purpose and then details each mode, filters, and response fields. While every sentence carries information, the length could be trimmed slightly without losing essential guidance.

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

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

Given no output schema and the complexity of a three-mode arbitrage tool, the description covers return structure (opportunities[], partition_check), failure behavior (null arb signal), and limitations (fill check with realizable edge). It also references a related tool for deeper analysis, making it self-contained for an agent.

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

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

Schema coverage is 100% and both parameters have descriptions. The main description adds value by providing concrete examples (e.g., 'fed-decision-may-2026') and clarifying that full URLs are accepted for `event` and that `topic` searches related events. This enhances semantics beyond the schema.

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

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

The description opens with a specific verb-resource pair ('Find arbitrage opportunities on Polymarket') and details the method (monotonicity violations + partition-sum checks). It clearly distinguishes the three invocation modes (no args, event, topic) and their intents, which also differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states when to use each mode: `event` recommended for a specific market, `topic` for cross-event scanning, and no args for trending scan. It also names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This satisfies the when/alternative criterion.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond that by disclosing caching ("Cached 1h at the KV level keyed on all knobs"), diagnostic availability ("_diagnostics{...} so callers can see WHY a segment is empty"), and detailed model behavior (e.g., placeholder-slug filters, per-sport alpha). This rich behavioral context is additive and non-contradictory.

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

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

The description is a single dense paragraph, not front-loaded with structure. However, every sentence carries relevant information (model families, knobs, diagnostics, caching), so it earns its place. It could benefit from bullet points or section breaks, but the density is justified given 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 thoroughly details the response shape: by_segment, fed_candidates/fed_note, and _diagnostics with funnel counters. It also covers edge metrics (edge_pp_net, kelly_fraction), caching, and tradeable-edge filters, making it complete for an agent to understand what to expect and how to act.

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%, yet the description adds substantial meaning beyond field-level docs. For instance, it explains that min_partition_leg_kelly applies to per-leg Kelly within top_legs because "Partition arbs always return kelly_fraction_half=0 at the parent level by design," and clarifies slippage_pp with market context ("Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade"). This elevates parameter understanding well 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." It further differentiates from siblings by detailing three response segments (model_driven, structural_arbitrage, concentrated_longshot) and mentioning "FIVE MODEL FAMILIES," making the tool's scope 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 clearly states when to use it: "Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets." It also provides explicit knob guidance (e.g., "Set to 2 to require tight books," "Set to 5000 to drop thin-book opportunities") and warns about unreliable signals ("1m-T vs EFFR signal is unreliable at meeting-month horizons"), effectively covering when and when-not scenarios.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true; the description adds significant behavioral detail: snapshots are written on cache-miss, gaps mean no scan, decay uses daily closes net of slippage, history bounded by 60-day TTL, and the signed nature of edge_pp_net with SELL YES negative. 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 well-structured: core purpose, args, response breakdown, and limits. Each sentence carries substantive information (e.g., 'the median lifespan is your competition clock'), and it's front-loaded with the key question it answers.

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

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

With no output schema, the description thoroughly details the response structure (tracked[], expired[], snapshot_dates[]) and explains edge cases (snapshot gaps, TTL, intraday vs daily closes). For a 2-param read-only tool, this is complete.

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

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

Schema description coverage is 100%: both 'days' and 'window' are fully described in the schema. The description repeats 'days (lookback, default 14, max 30)' and 'window (snapshot family, default 1wk)' without adding new meaning beyond the schema, so baseline 3 applies.

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

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

The description opens with 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly frames the tool's question: 'how long has this edge existed and is it shrinking?'. This gives a specific verb and resource, clearly distinguishing it from siblings like polymarket_edges which likely provides current edge data.

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

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

The description implies usage context: this is for historical persistence/decay analysis, not current edges, and even illustrates a use case ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it never explicitly names alternatives or says 'use this when...' versus siblings, so it's clear but not explicit about 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=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds rich behavioral detail: it walks the order book ladder, computes VWAP fill and slippage, returns a verdict (clean|degraded|cannot_fill), and warns about partial basket fills becoming unhedged directional positions. This goes far beyond the annotations.

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

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

Although the description is long, every sentence contributes operational information or critical warnings. It is front-loaded with the core purpose, then methodically covers mode requirements, parameter semantics, return fields, and usage context. No filler or redundant restatement of the schema.

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

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

There is no output schema, so the description must carry the full burden of explaining return values. It does this thoroughly for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, and forced_directional_risk. Given the tool's complexity, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. However, the description provides substantial added meaning for every parameter: it defines single-market vs basket modes, explains the dual interpretation of size_usd (max spend on buys vs target proceeds on sells vs settlement notional in basket mode), and details the default behavior for `side` in basket mode. This significantly exceeds the 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 phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth', clearly stating the tool's function and scope. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by framing this as the pre-trade fill-risk validation step.

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 given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' This clearly states when to use the tool, and the context explains why (theoretical overround on thin books is not capturable, partial fills convert arbs into unhedged positions).

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 well beyond the annotations, disclosing safety fields like compatibility_warning scenarios, temporal_alignment, and skipped comparison counters. It also explains the tool's behavior when bet shapes are non-equivalent ('the tool says so') and warns that real spreads are rare, providing deep behavioral context.

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

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

The description is front-loaded with purpose and effectively structured with labeled sections (SAFETY FIELDS, MODES). It is long, yet every sentence adds value given the tool's complexity. Slightly verbose, but not wasteful.

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 response structure (leg-by-leg prices, matched spread, top_spreads_pp) and all safety fields in detail. It thoroughly covers both usage modes and caveats, making it highly 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?

The schema already covers parameter descriptions 100%, but the description adds the conceptual relationship between parameters: the two modes (topic vs. explicit ticker/slug) and that explicit parameters override the topic-mapped side. This enriches understanding beyond the raw schema descriptions.

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

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

The description clearly states a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes this from sibling tools like polymarket_arbitrage by focusing on the cross-venue spread calculation and the nuanced compatibility checks it performs.

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 the tool, including two explicit modes (topic shortcuts vs. explicit event pairing) and behavior caveats (e.g., 'pre-mapped ≠ tradeable'). However, it does not explicitly mention alternatives or when-not-to-use this tool versus sibling tools like polymarket_arbitrage.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds that it returns decoded content and extracts text/URLs, which complements the safety profile without contradicting the annotations.

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

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

The description is brief and front-loaded with the action, but there is slight redundancy across the three sentences (extract, returns, read stored). Still, it is appropriately sized and every sentence adds some value.

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

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

With a single well-documented parameter, an output schema, and clear annotations, the description provides all necessary context for this simple tool. It covers the action, return value, and use case, leaving no major gaps.

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

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

The single parameter 'url' is already well-described in the schema as a publicly accessible URL to a QR code image. The description does not add further details about parameters, so it relies on the schema's high 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 decodes QR code images to extract embedded text or URLs. It distinguishes itself from the sibling tool create_qr by explicitly focusing on reading/decoding rather than generating.

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 to use when you need to read what's stored in a QR code, giving clear context. However, it does not mention alternatives or when not to use, which for a simple tool is acceptable but not fully exhaustive.

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

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

Annotations already state readOnly/idempotent/non-destructive, and the description adds meaningful context: scoping to anonymous IP, BYO key hash, or account ID, and the behavior of omitting key to list all saved keys. 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 main function, followed by usage, scoping, and sibling relationships. Every sentence contributes useful information with no filler.

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

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

For a simple one-parameter tool with strong annotations, the description covers both retrieval and listing modes, scoping, and how it relates to remember and forget. No critical gaps remain.

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

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

Schema coverage is 100% for the single key parameter, with its description already explaining 'omit to list all keys'. The tool description reiterates this but adds no new parameter semantics beyond what the schema provides, 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 explicitly states it retrieves a saved value or lists all keys with concrete examples like target ticker, address, and research notes. This clearly distinguishes it from sibling tools remember (save) and forget (delete).

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 says to use it for looking up previously stored context 'without re-deriving it from scratch' and explicitly pairs with remember to save and forget to delete. The scoping by identifier further clarifies when it applies.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals that events carry source, citation_uri, and raw payload, and that mark_read:true mutates read state so subsequent calls return only newer events. It also mentions persistence and the public mirror endpoint, adding substantive behavioral context with no contradiction.

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

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

Three dense sentences front-load the core purpose, then filter options, then operational guidance. Every sentence contributes new information; 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?

With no output schema, the description compensates by specifying the key fields in each returned alert and explaining filter/read-state behavior. It also addresses operational concerns (polling, alternative endpoint), making the tool self-sufficient for an agent despite five 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 covers all five parameters, so baseline is 3; the description adds value by giving a concrete type example ('sec_8k'), clarifying since as an ISO timestamp, and explaining the semantic consequence of mark_read ('next call only shows newer ones'). This goes beyond the schema without restating it.

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

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

The description opens with 'Pull fired events from your subscription feed,' naming a specific action and resource. It further details the return contents (source, citation_uri, raw payload) and distinguishes this from general tools by focusing on the evaluator's persisted alert feed.

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 explains that polling works fine and points to an alternative HTTP endpoint for scripts/dashboards, providing clear usage context. It does not explicitly enumerate when to use this over sibling tools like recent_changes, but the feed-specific language implies the appropriate scenario.

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

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

Annotations declare readOnlyHint/idempotentHint, but the description goes far beyond by detailing fan-out to SEC EDGAR, GDELT→GNews fallback (with rate-limit/5xx conditions), and USPTO soft-fail after sunset. It also describes return structure and citation URIs, adding substantial behavioral context not present in 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 well-structured: example queries first, then mechanism, parameters, output, and alternative. Every sentence covers a distinct aspect with no filler. The length is justified by the tool's multi-source 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?

For a tool with no output schema and multi-source fan-out, the description covers all necessary context: input formats, source behaviors, fallbacks, output shape (changes[] + total_changes + citations), and alternative tool. It is complete for an agent to decide when to invoke and 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?

Schema coverage is 100%, so baseline is 3. The description adds useful guidance beyond the schema: explains ISO vs relative shorthand for `since`, recommends '30d' or '1m', and clarifies that `type` only supports 'company'. This extra meaning justifies a 4.

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

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

The description opens with clear example queries and defines a specific verb+resource: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly distinguishes from entity_profile, which covers static profile material, 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?

Provides explicit usage context ('What's new with X' / 'latest on Y') and an explicit alternative: 'Use entity_profile instead when you want the static profile.' It also gives parameter usage tips for `since`, such as 'Use 30d or 1m for typical monitoring.'

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

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

The description discloses authentication-dependent persistence (authenticated users get persistent memory, anonymous sessions retain memory for 24 hours) and scoping by identifier, which goes beyond the annotations' idempotency hint. 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 three sentences with no fluff, front-loading the core action first and quickly moving to usage and persistence details. Every sentence provides new information about purpose, when to use, or behavior.

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?

As a simple key-value store tool with no output schema, the description covers purpose, usage scenarios, persistence behavior, and related tools, which is complete for its complexity. The annotations provide idempotency, so the lack of detail on overwrite behavior is acceptable.

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 fully documents both parameters with 100% coverage, so the baseline is 3. The description adds the key-value pair concept and scoping by identifier, but this is more about storage behavior than parameter-specific semantics. The schema's examples already cover key and value expectations.

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 with 'Save data the agent will need to reuse later,' specifying both the verb (save) and the resource (data for later reuse). It distinguishes itself from siblings by explicitly mentioning recall and forget as paired tools for retrieval and deletion.

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 context for when to use it: 'Use when you discover something worth carrying forward...' with concrete examples. It also provides guidance on complementary tools by saying 'Pair with recall to retrieve later, forget to delete,' making the decision framework clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond this: it explains that unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, and that LEI/FIGI enrichment degrades gracefully if external sources are unavailable. It also discloses internal cascading lookups, giving the agent a clear model of behavior.

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

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

The description is front-loaded with example queries and a clear purpose statement. While it is fairly long, every sentence adds useful information—types, sources, degradation behavior, and output details. It could be tightened slightly, but it earns its length given the tool's complexity.

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

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

Despite lacking an output schema, the description thoroughly explains return values: identifiers, source labels, unresolved list, and citations for drugs. It covers two entity types, input formats, fallback behavior, and the internal multi-endpoint cascade, making it complete for an agent to invoke 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%, so parameters are well-documented in the schema. The description adds contextual semantics by explaining what each entity type returns (e.g., company returns CIK, ticker, LEI, FIGI; drug returns RxCUI), which helps the agent choose the correct type. It also elaborates on accepted value formats with examples, contributing beyond the schema's 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 resolves a user-spoken NAME to canonical/official identifiers other tools require. It gives specific examples ('What's the ticker for…') and differentiates itself by saying 'Use FIRST whenever you have a name but need an ID.' This distinguishes it from siblings like entity_profile or compare_entities.

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 FIRST whenever you have a name but need an ID.' This serves as a when-to-use instruction. It also implies when-not-to-use (if you already have an ID). The description notes it replaces 2-3 manual lookups, reinforcing its intended role as a preliminary lookup tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it internally probes with ai_visibility_check and returns a ranked list with score, confidence, and signal density. This provides useful behavior beyond annotations, though it doesn't detail rate limits or potential side effects.

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

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

The description is concise and front-loaded: first sentence states purpose, second explains mechanics, third gives a use-case example. Every sentence contributes value with no redundancy.

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

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

Given the moderate complexity and absence of an output schema, the description sufficiently explains the return format (ranked list with score, confidence, signal density). It also clarifies the entities parameter nuance (first entry as subject). Could mention entity limits explicitly, but those are in the schema.

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

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

Schema coverage is 100% for all parameters, so the baseline is 3. The description reinforces the entities semantics but does not add significant meaning beyond what the schema descriptions already provide.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks by score. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the exact method and output.

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

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

It provides a clear use case ('competitive AI-marketing audits') and an illustrative example. However, it does not explicitly say when not to use this tool or mention alternatives, though the context makes it obvious for multi-entity comparison tasks.

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 readOnlyHint/idempotentHint annotations by disclosing that the tool calls external APIs, explains graceful degradation of partial failures, warns that first bundlephobia measurement can take 5-30s, and mentions the sources_failed field. This gives the agent rich behavioral context without contradicting annotations.

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

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

The description is dense but well-organized: purpose first, use cases, return structure, ecosystem scope, and failure behavior. Every sentence carries important information, with no fluff. It's a bit long, but the complexity of the tool 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 the tool's complexity (multiple external sources, return summary block, partial failure handling), the description covers all critical aspects: what it fans out to, what fields are returned, ecosystem limitations, and operational caveats. Even without an output schema, the description lists the summary block fields, making the return format clear.

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 description doesn't need to elaborate much. It does add the semantic context that the package must be an npm package and that version is optional (defaulting to latest in schema), but this is already present in the schema. No significant extra meaning is added over the schema's parameter descriptions, so baseline 3 is appropriate.

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

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

The description immediately states the tool's exact purpose: a composite 'should I add this npm package to my project' check that fans out to deps.dev and bundlephobia. It lists specific data points (license, advisories, version history, bundle size, tree-shake support), clearly distinguishing it from sibling tools that focus on markets or 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?

Explicitly states when to use: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Even provides an exclusion: non-NPM ecosystems (PyPI/Maven/Cargo/Go) should fall under deps.dev:version directly, guiding agents to alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the embedding model (BGE-base-en), similarity method (cosine over 500-char overlapping windows), the 200K char cap with truncation flag, and that results include offsets for verification. These are meaningful behavioral details not available in 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 front-loaded with the core purpose, then efficiently covers usage, output, pairing, and technical details. Every sentence adds distinct value without fluff or tautology, and the structure flows logically from what to when to how.

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 compensates by explaining the return format ('top-N passages with character offsets and similarity scores'). It also covers the truncation behavior, the use case, and the complementary tool, making it fully self-contained for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters well. The description adds a few contextual examples (e.g., SEC 10-K body, article) but does not introduce new parameter semantics beyond the schema's descriptions. 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 opens with 'Semantic search INSIDE a fetched record,' which clearly identifies the verb ('search'), resource ('fetched record'), and distinguishes it from broader search or grounding tools. It also states the concrete output: 'top-N passages with character offsets and similarity scores.'

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also names a complementary/alternative tool: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear context and 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?

Adds substantial behavioral context beyond annotations: OAuth requirement, persistence limitations, SMS 10/day cap, phone verification at /account, webhook HMAC signing secret returned once, and auto-disable after 10 failures. This complements the idempotentHint and openWorldHint annotations 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 structured with purpose first, then requirements, types, and delivery channels. It is dense but every sentence provides necessary operational detail; no filler or redundant statements. The structure allows quick parsing despite the 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?

For a subscription tool with nested delivery object and five types, the description covers required auth, return value, all type-specific parameters, delivery options, and failure behaviors. Although there is no output schema, the description still tells the caller what they receive (subscription id) and how delivery works.

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?

Though the schema has 100% parameter coverage, the description adds concrete examples for each type (sec_8k items, polymarket_edge topic, fred_series series_id) and clarifies delivery constraints not present in the schema, such as phone verification, webhook secret behavior, and the 10/day SMS cap.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly identifies the action and resource, and the mention of delivery channels and types distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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?

Includes explicit prerequisites ('Requires a Pipeworx OAuth account; anonymous + BYO cannot persist') and explicit alternatives for consuming alerts ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). It also enumerates supported subscription types, giving clear guidance on when to use the tool and what configurations are possible.

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

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

Annotations already declare the tool read-only, idempotent, and open-world, and the description does not contradict these. It adds useful behavioral context about the live catalog (thousands of tools) and the response format (category buckets with tool+argument examples), going beyond what annotations alone convey.

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

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

The description is long but information-dense, covering examples, purpose, output, parameters, and usage in one paragraph. It slightly buries the core purpose statement after an initial list of example queries, but the structured punctuation and clear sections make it scannable. 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?

For a tool with one optional parameter and no output schema, the description fully covers all needed information: what it returns (category-bucketed example questions), how to customize via `topic`, and when to use it first. The absence of an output schema is compensated by an explicit description of the return format.

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

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

The schema fully documents the `topic` parameter with allowed values and behavior (omit for spread). The description's examples ('finance', 'pharma', 'betting') and 'call with no arguments' phrasing largely mirror the schema, adding no fundamentally new semantic information. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose as 'the onboarding entry point' and explains that it returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from sibling tools like ask_pipeworx and discover_tools by framing it as the first-stop orientation tool for a newly connected agent.

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 instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools,' providing strong when-to-use guidance. It also explains the two invocation modes (no args vs. topic). However, it does not explicitly name alternatives or state when not to use it, leaving a small gap.

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

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

The description adds significant behavioral context beyond annotations: ownership enforcement, row deactivation rather than deletion, and the availability of historical events via recent_alerts. This details the side effects and constraints that annotations do not cover.

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

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

The description is two sentences, front-loaded with the core action, and each sentence adds valuable information. No filler or redundancy.

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

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

For a single-parameter tool with annotations and no output schema, the description covers purpose, constraints, and side effects, and even connects to recent_alerts for understanding history preservation. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The schema already provides full coverage (100%) for the id parameter, including its format and origin. The description adds no additional parameter meaning beyond referencing 'id' and ownership, 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 cancels a subscription by id, with a specific verb and resource. It distinguishes from siblings like subscribe and list_subscriptions by specifying the cancellation action and the id-based target.

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

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

The description provides clear context about ownership enforcement and the deactivation behavior, which implies when to use it (cancelling your own subscription). However, it does not explicitly state alternatives or when not to use it, though the sibling list includes subscribe for the opposite action.

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 declare readOnly/openWorld/idempotent; the description goes far beyond that by detailing the two routing paths, the full verdict enumeration, and the crucial caller caveat that could_not_verify means the check did not happen and must not be presented as evidence. This is exactly the behavioral nuance an agent needs and 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?

The description is front-loaded with the purpose and common query patterns, then flows into routing, return values, and error distinctions. It is longer than average but every sentence contributes useful information. The 'Replaces 4–6 sequential calls' line is a mild value-add that could be trimmed, but overall it is well-structured and not bloated.

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

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

With no output schema, the description carries the burden of explaining return values; it lists verdict types, the actual value with citation, reasoning, and error semantics (could_not_verify vs unsupported). It also explains the two routing paths and the replacement of a multi-step sequence. This gives the agent a complete mental model for invoking and interpreting the 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% and both parameters are described, so the baseline is 3. The description adds meaningful context about tolerance_pct: it can override the implied tolerance, recommends values 1–2 for hallucination detection, and notes the default cap of 5. This goes beyond the schema's dry parameter description, justifying a 4.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources, with a specific verb ('validate'/'verify') and resource ('claim'). It distinguishes itself from siblings by describing a single-call fact-checking tool that handles company-financial claims via SEC EDGAR and all other claims via a grounded pipeline, returning a verdict and evidence.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and adds that it replaces 4–6 sequential calls, implying when it is more efficient than a multi-step pipeline. However, it does not name sibling tools or state when NOT to use this tool, so it falls slightly 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.