Victorian Complaint

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond annotations: default model (Workers AI Llama-3.3-70b) is free, passing _apiKey invokes Anthropic with direct payment to Anthropic, and the return structure includes per-model fields. This covers auth/cost behaviors that annotations do not.

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 front-loaded action. It efficiently covers purpose, default behavior, return format, and use cases without redundancy. Every sentence adds substantive value, and there is no verbosity.

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

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

The tool has no output schema, so the description's inclusion of the return format ('per-model {score, confidence, signals, raw_response} + combined view') is essential and provided. It also covers default, auth, and use cases. Minor gaps exist (e.g., behavior for invalid model names or rate limits), but for a read-only probation tool with strong annotations, it is largely 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. The description adds meaning beyond the schema by explaining the default model behavior, the significance of _apiKey (BYO key with direct cost), and the role of `models` in selecting between free and paid probes. This enhances interpretation of the 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 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.' This distinguishes it from siblings like ask_pipeworx (Q&A) and scan_competitor_ai_presence (competitor-specific) by emphasizing the visibility scoring output and multi-model probing.

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

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

The description provides clear use cases ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional _apiKey parameter. However, it does not explicitly name alternative tools or state when NOT to use this tool, leaving a small gap in exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds context about what happens internally: it routes to sub-tools, fills arguments, and returns structured answers with pipeworx:// citation URIs. This goes beyond annotations without contradicting them, though it omits details like rate limits or error 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 a strong directive and includes structured guidance, examples, and alternatives. While it is somewhat lengthy, every section serves a purpose: the 'PREFER OVER WEB SEARCH' call-to-action, the explicit trigger phrases, and the sibling differentiation justify the length. It is not bloated or redundant.

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

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

For a general-purpose intelligencer tool with no output schema, the description covers the essential context: what it does, when to use it, how to think about limitations, and what the response includes (structured answer with citations). It also mentions the breadth of sources and gives concrete examples. The only missing piece is a clearer statement on what it cannot answer, but given the breadth and open-world annotation, it is adequately 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?

The schema description coverage is 100% for all parameters, with each alias (q, text, input, query, prompt) explicitly described. The description adds no new meaning beyond what the schema provides; it merely repeats that 'question' is the primary parameter. No extra parameter semantics are needed for this simple, single-field input.

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 what the tool does: it routes questions to the right tool among 5,529 across 1455 verified sources, fills arguments, and returns structured answers with stable citation URIs. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by explicitly describing the trade-offs.

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 this tool: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and provides concrete step-up conditions ('for a hallucination-resistant single answer use ask_pipeworx_grounded; for a broad/multi-part question use deep_research'). It also lists trigger phrases and examples, making the decision boundary clear.

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

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

The description adds valuable context beyond the annotations: it reveals that the tool is a full working router ('Falls back to nothing — this IS a full working router'), that its routing may change depending on active candidates, and that it currently matches ask_pipeworx exactly since the last candidate was retired. It also discloses the response shape is identical to ask_pipeworx. Annotations already declare readOnlyHint and idempotentHint, which the description does not contradict.

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

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

The description is four sentences long and efficient, front-loading the core identity ('Beta version of ask_pipeworx') and then covering current state, usage, and the fact that it is a full router. It is slightly longer than the two-sentence ideal, but every sentence carries useful, non-redundant information.

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

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

Given the simple one-input schema, comprehensive annotations, and absence of an output schema, the description is complete enough for an agent to understand what the tool does, when to use it, and what to expect. It references ask_pipeworx for the response shape, which is acceptable given the sibling relationship, though it is not fully self-contained.

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

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

The input schema has 6 properties but they are all aliases for the single required 'question' parameter, and the schema's own descriptions fully explain the aliases (100% coverage). The tool description adds no additional parameter semantics, so it earns the baseline score of 3 for high schema coverage.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by noting the experimental routing improvements and from ask_pipeworx_grounded by emphasizing it is identical to ask_pipeworx.

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

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

The description gives a concrete usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also implies the stable router is the alternative for non-experimental use, but it does not explicitly name other sibling tools like ask_pipeworx_grounded as alternatives.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the refusal behavior with specific refusal_reason enum values, the success return payload structure, and that it incurs an extra LLM call. This adds substantial contextual detail that the annotations alone do not convey, with no contradiction.

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

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

The description is concise yet information-dense: each sentence contributes unique value, from the mode definition and routing mechanism to the return format, usage cases, and cost tradeoff. It is front-loaded with the core purpose and stays structured and readable despite covering complex 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?

Even though there is no output schema, the description explicitly details the success return fields (answer, evidence, confidence, source, fetched_at, refusal_reason) and failure refusal_reason values. It also explains the routing scale, the grounding constraint, and when to use it, making it fully complete for a high-stakes answer tool.

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

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

The input schema covers all parameters with 100% description coverage, including the primary 'question' parameter and its aliases (q, text, input, query, prompt). The description only mentions 'fills arguments' generically and does not provide additional parameter-specific meaning, so the schema already carries the burden and a baseline score of 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and emphasizes that it 'EXTRACTS the answer using ONLY what the tool result contains.' This distinguishes it from the sibling ask_pipeworx by highlighting grounding and explicit refusal 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 when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples like financial verdicts and legal claims. It also directs users to 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost, clearly differentiating it from the alternative.

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

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

Annotations already mark it readOnly, openWorld, idempotent, non-destructive, but the description goes far beyond: it details the resolver contract (market_match_confidence, alternatives, suggestions), safety short-circuits for low-confidence matches, closed/dead market handling, wide-spread market flags, news fallback fields, and cancellation-rule risk with ev_impact. It adds deep behavioral context that an agent needs to interpret results correctly.

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

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

Despite being long, it is highly structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.), front-loaded with purpose, and every sentence provides actionable detail. No filler or redundancy; the length is justified by the tool's complexity.

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

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

With no output schema, the description takes on the burden of explaining return shapes, edge cases, and safety states. It covers response fields (market, analysis, evidence), resolver alternatives, parent-event extraction, news fallback, and cancellation rules, leaving no important behavior unspecified.

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 good param descriptions. The description adds extra meaning by explaining fan-out examples for different market types, the effect of depth on evidence sources, and the include_raw tradeoffs in response size. This goes beyond the schema's basic type/enum descriptions, so it earns above baseline.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings like polymarket_edges or validate_claim by focusing on the research/fan-out behavior. Examples and classifiers further cement its unique role.

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

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

The description explicitly states when to use it: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives clear usage context and even mentions blocking conditions. However, it does not explicitly say 'don't use when...' or name alternative sibling tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, but the description adds substantial context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, return format with citation URIs, and the efficiency claim of replacing 8–15 lookups. Enhances the agent's understanding 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 dense but not overly long; the initial trigger phrase list is useful for matching user intent, and each sentence contributes functional information. Slightly verbose in the trigger examples, but earns its place for an AI agent.

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 explains the return type ('paired data + pipeworx:// citation URIs') and sorting behavior. It covers the two parameter types, data sources, and edge-case handling (off-calendar fiscal years). Minor gaps include the exact structure of 'paired data', but this is adequate for invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful nuance to the 'type' parameter by specifying what data each entity type pulls (e.g., 'company' pulls latest 10-K revenue, 'drug' pulls FAERS counts). This goes beyond the schema's simple enum description.

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

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

Description clearly states a specific verb+resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It also includes trigger phrases and explicitly contrasts with sequential single-pack lookups, distinguishing it from sibling tools like entity_profile.

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

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

Provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Defines use cases for company vs drug types with concrete examples. Does not explicitly mention when *not* to use it (e.g., for single entity lookups), but the emphasis on comparison makes this implicit.

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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral detail: it 'returns a findings packet' with 'gaps[] for facets the data couldn't answer (never invented)', explains deep-research routing to 5,529 tools, semantic excerpting, latency expectations, and the guarantee that citations are fetchable. No contradictions with annotations.

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

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

The description is long and dense, but every sentence adds valuable information—account prerequisites, alternatives, limitations, depth semantics, output format. However, it is a single unbroken paragraph without clear sectioning, which slightly harms scannability for an AI agent. It earns a 4 rather than a 5 due to structural tightness.

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 must explain return values, and it does: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'. It also covers edge cases (news topics yield empty gaps), depth behaviors, and latency, making it fully 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?

Although schema descriptions cover both parameters 100%, the description adds significant semantic depth. It explains that `question` can be broad/multi-part and that `depth` controls facet count (quick=3, standard=5, thorough=8), hop behavior, contradiction scans, and the paid requirement for thorough. This goes well beyond the schema's documentation.

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

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

The description clearly states the tool's core function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in ONE call. It explicitly differentiates from siblings by saying 'this is NOT open-web search' and contrasts with ask_pipeworx, making its unique role 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 offers explicit usage guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also provides an account-based fallback: 'If you are not signed in, use ask_pipeworx instead'. This gives clear when-to-use and when-not-to-use instructions with named 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 this a safe, read-only, idempotent operation. The description adds behavioral context beyond annotations: it returns top-N most relevant tools with names, descriptions, and full input schemas, and notes results are 'ready to call directly, no second schema lookup needed.' This discloses what the tool actually returns and its convenience aspect, which is not captured by 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 somewhat long due to the domain list, but it is front-loaded with purpose and usage. Each sentence serves a function: purpose, usage scenario, output details, and call-first recommendation. The domain list is verbose but adds useful context for an agent trying to decide if this tool covers their need. Overall, it's efficiently structured 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?

Despite having no output schema, the description clearly explains what the tool returns (top-N tools with names, descriptions, full schemas, curated examples). It also covers when to use it and the fact that results are ready to call directly. This is sufficient for an agent to understand the tool's role and expected output, though it could mention the 'limit' parameter to control N, which is left to 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?

The input schema has 100% description coverage, with 'query' thoroughly documented and aliases listed. The description itself does not add parameter-level meaning beyond the schema, but it reinforces the natural language nature of the query. Since schema covers all parameters, baseline 3 is appropriate; no compensation needed.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this as a meta-tool for discovering other tools, not for performing the task itself. The explicit list of domains (SEC filings, financials, FDA drugs, etc.) further clarifies scope and differentiates it from sibling tools that operate on specific 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?

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist.' It also gives a strong directive to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent exactly when to invoke this tool and implies it should be used before other specialized tools.

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

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

The description discloses behavioral traits beyond annotations: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields and URIs, orders fundamentals by period_end DESC, uses a GDELT→GNews fallback, soft-fails for the USPTO API sunset, and requires a zero-padded CIK. This adds substantial context beyond the readOnly/idempotent hints.

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

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

The description is long but information-dense. It front-loads user intents and immediately follows with the tool's core value proposition and output breakdown. Some redundancy exists (e.g., 'names not supported' appears twice, and the query examples are numerous), but each detail serves the agent's understanding. Overall, it earns its length for a tool with this complexity.

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

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

With no output schema, the description fully enumerates return fields (cik, company_name, recent_filings with URIs, fundamentals sorted, patents, news, LEI). It also documents input constraints, error handling for patents, and cross-tool fallback. For a read-only research aggregator, this is complete and self-sufficient.

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

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

The schema already covers both parameters in detail (type enum, value format with examples), so the baseline is 3. The description adds extra value by reinforcing the zero-padding requirement ('0000320193'), providing concrete input examples ('AAPL'), and cross-referencing resolve_entity for name-based input. However, it does not introduce fundamentally new semantic info beyond the schema, justifying a 4 rather than 5.

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

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

The description starts with a clear verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It also includes numerous example queries ('Tell me about X', 'research Acme') and explicitly distinguishes itself from chaining single 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 provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' This differentiates from sibling tools like resolve_entity and deep_research.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds useful context by specifying what gets destroyed ('a previously stored memory by key') and the rationale for deletion ('clear sensitive data'). It does not contradict annotations.

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

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

The description is three concise, well-structured sentences. It front-loads the action, then gives usage guidance and relationship to siblings. Every sentence 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 1-parameter tool with no output schema, the description covers purpose, usage, and relationship to related tools. It omits edge-case behavior (e.g., deleting a non-existent key), but the idempotentHint annotation implies this is safe, so completeness is good.

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

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

The schema already fully documents the only parameter ('key' with description 'Memory key to delete'), providing 100% coverage. The description only restates the key concept without adding additional syntax, format, or behavioral details beyond the schema.

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

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

The description starts with 'Delete a previously stored memory by key', which is a specific verb+resource action that clearly distinguishes it from sibling tools like remember (store) and recall (retrieve). It unambiguously states the tool's function.

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

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

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. It also positions the tool within a memory workflow by saying 'Pair with remember and recall', but it does not explicitly state when NOT to use it or list specific alternatives as exclusions.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals that the tool 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' adding context about network retrieval and output format. It could mention error handling or rate limits, but given strong annotations, this is sufficient.

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

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

The description is three concise sentences plus a 'Useful for' list. The opening sentence states the purpose immediately, the second explains the mechanism, and the third specifies the output format. Every sentence earns its place, with no wasted words.

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

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

For a simple tool with 2 parameters and no output schema, the description adequately covers output ('single text blob ready to drop at site-root/llms.txt'), process, and use cases. It doesn't mention max_links configuration, but the schema covers that, and the tool's simplicity warrants a 4 rather than a 5.

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

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

The input schema fully describes both parameters (url and max_links) with 100% coverage. The description mentions 'for any URL' but doesn't add any meaning about max_links beyond what the schema already states. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly states it 'Generates a production-ready llms.txt file for any URL' and explains the process (fetches the page, extracts title/description/key links, emits standard markdown). This specific verb+resource combination distinguishes it from sibling tools like scan_competitor_ai_presence or ai_visibility_check, which focus on scanning/checking rather than generating an output file.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' While it doesn't name alternative tools or explain when not to use it, the context 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 readOnlyHint=true and destructiveHint=false, so the bar is lower. The description adds value by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying the caller-scoped nature of the listing, which is 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 two concise sentences: first states purpose, second lists return fields and gives usage direction. No filler, well front-loaded.

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

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

For a simple list tool with full schema coverage, safety annotations, and a description that covers return fields and usage scenarios, all necessary context is provided. No gaps remain for the 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% with include_inactive fully described. The description adds no parameter-specific details, but the schema already carries that burden, so the baseline 3 applies.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes from sibling tools like subscribe/unsubscribe by specifying caller-scoped active subscriptions and the exact return fields.

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

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

The description provides explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This helps the agent choose this tool over alternatives and connects it to the unsubscribe workflow.

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?

With all annotations set to false, the description carries the full burden of behavioral disclosure. It explains the claim_token flow ('Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), rate limiting ('Rate-limited to 5 per identifier per day'), and the fact that it is free and doesn't count against quota. It also notes that the team reads digests daily, providing expectations on response time.

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 sizeable but every sentence contributes unique information: purpose, types, exclusion, claim_token flow, rate limit, and cost. It is front-loaded with the core purpose and structured logically. 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 four parameters (including a nested object), no output schema, and no helpful annotations, the description covers all necessary context: how to submit, what to include, how to follow up, and what to expect (token, status, changes). It even addresses edge cases like 'Not sure?' and redirects off-topic feedback. This is fully complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the claim_token lifecycle (how to use it to check status), directing users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' and clarifying the meaning of the type enum values. This elevates the parameter understanding beyond the schema alone.

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

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

The description clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the specific feedback types (bug, feature/data_gap, praise) and confines its scope to 'tools served by this Pipeworx connection,' distinguishing it from any sibling tools that might collect feedback. The verb 'Tell' is specific and the resource is explicit.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is an exemplary usage guideline.

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

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

While annotations already establish read-only, idempotent, and non-destructive behavior, the description adds valuable context: 'Self-aggregating signal', 'derived from CF analytics-engine', 'no PII', and 'Cached 5min-1h depending on window'. This goes beyond safety to explain data source and freshness.

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 main purpose and uses a numbered list for usage scenarios, which aids scannability. A few details (e.g., 'derived from CF analytics-engine') could be trimmed, but overall every sentence adds value.

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

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

With no output schema, the description adequately explains the return types (top tools, packs, call volume). It covers caching, privacy, and usage context, making it sufficiently complete for a simple one-parameter read-only tool.

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

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

The schema already provides 100% coverage for the single 'window' parameter, including default and the difference between shorter/longer windows. The description merely repeats the enums without adding new meaning, so it stays at the baseline.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window' with specific time ranges. It also distinguishes itself from siblings by focusing on agent call trends, not general tool discovery.

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 'Useful for' section explicitly lists three distinct use cases (spotting hot data sources, confirming canonical tools, aligning use cases with agent needs). This is clear context, though it does not explicitly mention when not to use it or name alternative tools.

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

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

Despite readOnlyHint=true in annotations, the description goes beyond by explaining the algorithmic checks (monotonicity/partition-sum), thresholds (3pp, 0.30 Jaccard, 20% placeholder), and the fill-check logic with a 'do not trade it' condition. This is substantial context not available in structured annotations.

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

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

The description is long and dense, but each section (modes, semantic anchor, partition filter, response, fill check) is purposeful. It's front-loaded with the tool's purpose and mode selection. However, the level of detail borders on over-specification, so a 4 rather than 5.

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 explicitly lists the response fields (opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity violation context, partition_check). It also explains edge cases (null signal with >20% placeholders, realizable_edge_pp <= 0). This makes it highly complete for a complex tool.

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

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

The input schema already has 100% coverage with descriptions for both event and topic. The description adds examples, mode-specific guidance, and explains behavior like 'event (recommended for a specific market)' and what happens when no args are passed, enriching the parameter semantics.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It then details three invocation modes (trending_scan, event, topic), which clearly differentiates it from sibling Polymarket tools like polymarket_edges or 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?

It explicitly states when to use each mode: no args for trending_scan, event for a specific market, topic for cross-event scanning. It also points to polymarket_fill_risk for custom sizing, providing a clear alternative.

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

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

Annotations already declare readOnlyHint and idempotent, but the description goes far beyond that. It discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), a critical market-move warning ('your edge may already be in the price'), exclusions (Fed bets 'surface here, excluded from ranking' with a rationale), and diagnostic fields ('_diagnostics ... so callers can see WHY a segment is empty'). This is rich behavioral context well beyond the structured annotations.

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

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

The description is long but extraordinarily dense; every sentence adds critical information (model types, formulas, caveats, filters, response structure). It is well-structured with clear section markers (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). Length is justified by the tool's complexity, though it is less concise than a typical short description.

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 fully explain return values. It does: enumerates top-level response fields (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and model-specific details. It also explains why segments may be empty via diagnostics. Given the tool's complexity, the description is remarkably 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?

The input schema already covers all 9 parameters with detailed descriptions (100% coverage), giving a baseline of 3. The tool description adds value by grouping parameters into functional categories ('TRADEABLE-EDGE KNOBS'), explains their intent (e.g., 'drop opportunities where edge isn't realizable'), and clarifies edge cases like min_partition_leg_kelly applying to legs rather than the parent. This grouping and rationale goes beyond the schema's individual field descriptions.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It then clarifies the intended use case ('what should I bet on today') and distinguishes itself from merely listing markets by focusing on opportunity discovery with model families. This clearly separates it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 the tool ('Built for what should I bet on today — agents discover opportunities without paging hundreds of markets') and provides context on what it does (returns tradeable edges, filters by knobs, excludes unreliable Fed bets). However, it does not explicitly mention alternatives or when NOT to use it, so it falls short of a 5.

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

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

Even though annotations already declare readOnlyHint=true and idempotentHint=true, the description goes much deeper. It discloses that snapshots are written only on cache-miss, meaning gaps in snapshot_dates[] indicate no scan that day, that history is bounded by a 60-day TTL, and that decay numbers come from daily closes of edge_pp_net, not intraday. These are critical behavioral nuances that annotations cannot 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 every sentence earns its place. It is structured into clear sections: the purpose statement, the Args, the RESPONSE layout, and LIMITS. The information is dense yet efficiently organized, with no fluff or repetition. The front-loading of the core question the tool answers is excellent.

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 carries the full responsibility of explaining the return value. It thoroughly describes tracked[], expired[], and snapshot_dates[], including the meaning of 'trend', 'decay_pp_per_day', 'lifespan_days', and the signed nature of edge_pp_net. It also states limitations (TTL, snapshot gaps, daily closes). This is a complete and self-sufficient description for a 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 input schema already documents both parameters with descriptions (100% coverage). The description adds a little extra by framing 'window' as a 'snapshot family' and enumerating the allowed values, but overall it largely restates schema information. Since schema coverage is complete, the baseline of 3 is appropriate; the description gives marginal additional meaning.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It uses a specific verb ('tracker') plus resource ('Polymarket Edge') and further distinguishes itself by explaining it answers 'how long has this edge existed and is it shrinking?' This goes beyond a generic statement and differentiates it from sibling tools like polymarket_edges, which likely focus on current edges rather than historical persistence.

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 strong contextual guidance: it explains that a fresh wide edge and a 3-week-old wide edge are different trades, implying this tool is for assessing edge maturity. It also mentions the lookback window and snapshot defaults. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it stops short of full exclusionary guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description enriches behavioral understanding with specifics: it walks the order-book ladder, interprets size_usd differently for buys vs sells, clamps size_usd to 10–1,000,000, and names the output verdict and risk fields (thin_legs, forced_directional_risk). It also explains the danger of partial fills. No contradictions with annotations.

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

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

The description is dense but well-organized, separating single-market from basket modes and listing return fields. It uses all-caps for key warnings and mode distinctions, which aids scanning. However, it is quite long and could benefit from tighter formatting (e.g., bullets), though each sentence carries substantive information.

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

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

Given the tool's complexity, the description is remarkably complete. It explains both modes, return values, risk factors, and the operational context (when to use). Since no output schema exists, the description serves the role of documenting return fields and edge cases. It also clarifies the default side logic and the meaning of size_usd in each mode.

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

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

While the schema already covers all parameters (100% coverage), the description adds critical semantics: the default 'auto' behavior for side in basket mode based on partition sum, and the distinction between single-market size_usd (spend/target proceeds) and basket size_usd (settlement notional per leg). It also clarifies market vs event selection. The clamp range is mentioned in the description but not in the schema, adding value.

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 core function: a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It names specific output metrics (top_of_book, vwap_fill_price, slippage_pp, verdict) and distinguishes between single-market and basket modes. It contrasts with siblings by explicitly referencing polymarket_arbitrage and polymarket_edges, making its unique role clear.

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why, citing the risk of partial basket fills converting an arb into an unhedged directional position. This goes beyond vague context to actionable 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?

Even with readOnlyHint=true and destructiveHint=false in annotations, the description adds significant behavioral context: it details the response format (leg-by-leg prices, matched spread), explains the compatibility_warning conditions in two specific scenarios, describes temporal_alignment implications, and documents the skipped_cross_type/subtype counters. 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 lengthy but well-structured, front-loading the core purpose and then systematically covering modes, response, safety fields, and edge cases. Each section earns its place given the tool's complexity, though it could be tightened by trimming some redundant explanations (e.g., repeated warnings about pre-mapped ≠ tradeable).

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 full burden of explaining return values and behavior. It thoroughly covers the spread output, safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), and the conditions under which spreads are invalid. The description gives agents enough context to understand edge cases and interpret results correctly, making it highly complete for a complex tool.

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

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

The input schema already covers all three parameters with descriptions (100% coverage), providing a baseline of 3. The description adds value by elaborating on the topic shortcuts (listing examples and explaining the two modes) and explicitly stating that explicit tickers override the topic-mapped side, giving agents a clearer understanding of how the parameters interact.

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

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

The description clearly states the tool computes a 'cross-venue spread between Kalshi and Polymarket for the same resolving question', using a specific verb (compute/show) and identifying the exact resources involved. It also distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons and explicitly outlining two distinct modes (topic shortcuts and explicit tickers).

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

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

The description explains when to use the tool: when you need the cross-venue spread for the same question on both venues, either via pre-mapped topics or custom pairings. It also provides important cautionary guidance about the limitations of pre-mapped topics ('most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable'), though it does not explicitly name alternative tools or give when-not-to-use 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 establish read-only, idempotent, and non-destructive behavior. The description adds valuable context about scoping to the agent's identifier and the dual behavior of omitting the key to list all keys, which goes beyond the annotation metadata.

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

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

Four short, front-loaded sentences with no filler. The core action appears first, followed by usage context, scoping, and relationships. 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 simple key-value recall tool with strong annotations, the description is complete. It covers purpose, usage, scoping, and pairing with remember/forget. Even without an output schema, the return behavior (value or key list) is clearly implied.

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 describes the single optional 'key' parameter (100% coverage). The description reinforces that omitting the key lists all keys, but adds no new parameter-specific semantics beyond what the schema already provides.

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

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

The description opens with a specific verb-plus-resource construction: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes itself from sibling tools remember and forget, and provides concrete examples of stored context.

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

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

The description explicitly states when to use it: to look up previously stored context without re-deriving it. It also names related tools (remember, forget) for complementary actions, but does not provide an explicit 'when not to use' or alternative tool for a different 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?

The description discloses that setting mark_read:true will flag returned events as read and affect future calls, which is a mutating side effect. However, this directly contradicts the readOnlyHint: true annotation, as the tool can alter persisted state. This is an annotation contradiction, requiring a score of 1.

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 not bloated; it covers return contents, filtering, mark_read behavior, and an alternative endpoint in three sentences. Each clause adds relevant information, though it could be slightly more concise by dropping the URL detail.

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

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

Given there is no output schema, the description adequately describes return fields (source, citation_uri, raw payload) and core behaviors (filtering, mark_read, polling-compatibility). It is complete enough for a read-oriented tool with reasonable assumptions, but the annotation contradiction prevents a perfect score.

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 5 parameters with descriptions (100% coverage), but the description adds semantic value by explaining the intended use of type (with an example 'sec_8k'), since (ISO timestamp), and mark_read (how it affects subsequent calls). This goes beyond the schema's basic field descriptions.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed/alerts) and the verb (pull), and distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on fired/evaluator-written 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?

The description provides practical usage context: filtering by type and since, polling suitability ('Polls work fine'), and an alternative access method via a public URL for scripts/dashboards. It does not explicitly name sibling alternatives, but the context is clear enough for an agent to decide when to use this tool.

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

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

Annotations already convey read-only/idempotent/open-world, but the description goes further by disclosing the exact data sources, fallback logic (GDELT preferred, GNews on rate-limit/5xx), the PatentsView API sunset soft-fail, and output structure. This is substantive behavioral disclosure beyond annotations.

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

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

The description is dense but not bloated; it packs many specifics into a single paragraph. The opening query phrasing helps with intent matching, and every clause contributes functional detail. It is slightly long, but appropriate for a multi-source fan-out tool.

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

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

With no output schema, the description compensates by stating it returns 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also covers supported entity type, date formats, source fallbacks, and the main alternative tool, making it complete for a complex tool with no output schema.

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

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

The input schema already covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds minor but useful guidance—e.g., recommending '30d' or '1m' for typical monitoring and reiterating `since` shorthand examples—but mostly restates schema content.

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

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

The description clearly states the tool provides a change feed for a company over a time window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes itself from entity_profile by contrasting dynamic change feed vs static profile.

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

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

The description explicitly tells when to use this tool ('What's new with X') and when not to ('Use entity_profile instead when you want the static profile...'). It also describes fallback behavior between news sources, giving clear operational context.

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

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

Annotations already mark this as idempotent and non-destructive. The description adds valuable context: memory is scoped by agent identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours, and data is stored as a key-value pair. This complements 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 total: purpose, usage guidance, and persistence/companion tools. Each sentence earns its place, and the most important information is front-loaded. 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 simple two-parameter tool with no output schema, the description covers the essential aspects: what to store, when to use it, scope, persistence, and how to retrieve/delete. The annotations cover the safety profile, and the description fills in the operational details completely.

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

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

Schema already documents both parameters with examples, and coverage is 100%, so baseline is 3. The description adds semantic context by listing typical key categories (resolved ticker, target address, user preference) and clarifying that value can be 'any text — findings, addresses, preferences, notes,' which goes beyond the schema by conveying intent.

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 the specific verb 'Save' and clearly identifies the resource: 'data the agent will need to reuse later.' It also distinguishes from siblings by explicitly pairing with recall and forget, making the tool's role in the memory workflow unambiguous.

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

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

The description gives concrete when-to-use guidance: 'Use when you discover something worth carrying forward,' with examples like 'a resolved ticker, a target address, a user preference, a research subject.' It names alternative tools (recall/forget) but does not explicitly state when not to use this tool, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds graceful degradation, explicit `unresolved` identifiers, source labeling, and internal cascading lookups, providing context beyond annotations. No contradictions.

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

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

The description is lengthy but information-dense, front-loaded with example queries and structured around supported types. Every sentence adds value, though slight over-specification of internal mechanics like 'pipeworx://rxnorm/concept/{rxcui}' could be trimmed.

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

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

Given only two parameters and rich annotations, the description covers inputs, outputs, failure modes, source attribution, and graceful degradation. It is complete enough for an agent to invoke correctly, even without an output schema.

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

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

Schema covers both parameters with descriptions and one enum. The description enriches them with concrete examples (AAPL, 0000320193, 'ozempic') and detailed return semantics, exceeding the baseline for high schema coverage.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers other tools require as input. It distinguishes itself from siblings like entity_profile and compare_entities by focusing on ID resolution, with specific verbs and resource scope.

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

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

Provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' Includes example queries and supported types, giving clear context. Does not explicitly name alternative tools but implies this is the first step in a workflow.

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?

With annotations declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the safety profile is already clear. The description adds behavioral context beyond annotations: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This gives the agent a transparent understanding of the tool's process and output without contradicting the annotations.

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

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

The description is three sentences, front-loaded with the core purpose. Each sentence earns its place: the first states what it does, the second explains the mechanism and ranking, and the third provides a concrete use case and return summary. There is no fluff or repetition.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description is complete: it explains the core functionality, the process (probing and ranking), the return value (ranked list with score/confidence/signal density), and provides a practical usage scenario. The absence of an output schema is compensated by describing the response format. This 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?

The input schema has 100% description coverage for all 4 parameters, so the baseline is 3. The description adds a little context by framing entities as 'your brand + N competitors' and mentioning the 'subject' concept, but this largely mirrors the schema's description of the first entity as the subject. No additional meaning beyond the schema is provided.

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 'Compare AI visibility across multiple entities side-by-side', which is a specific verb+resource+scope. It goes on to explain the mechanism (probes with ai_visibility_check, ranks by score) and distinguishes itself from the sibling ai_visibility_check (which likely handles a single entity) by focusing on multiple entities and side-by-side comparison.

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

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

The description provides clear context for when to use the tool: 'Useful for competitive AI-marketing audits' with an example question. It implies that for a single entity check, one might use ai_visibility_check instead, but it does not explicitly state exclusions or name alternative tools beyond the implicit contrast. This is a clear context with no exclusions, so 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?

Beyond the readOnly/idempotent/destructive annotations, the description discloses composite fan-out behavior, partial failure degradation, a 5-30s latency for bundlephobia's first measurement, and the sources_failed field. This is rich, non-obvious behavioral context that annotations alone do not 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 compact yet dense; each sentence adds a distinct value: what it does, when to use, what it returns, ecosystem limits, and failure behavior. It is front-loaded with the purpose and uses structured punctuation (dashes, parentheses) to manage length without wasting words.

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

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

For a composite tool with no output schema, the description is exceptionally complete: it covers the summary block fields, per-advisory details, links, alternative versions, ecosystem scope, and graceful degradation with timeout behavior. Given the tool's complexity, this is more than sufficient for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, and the schema already describes both the package and version parameters. The description adds return-field context (is_latest, version history) but does not meaningfully clarify parameter semantics beyond what the schema provides. 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 is a composite npm package health check that fans out to deps.dev and bundlephobia. It specifies the exact resources (license, advisories, bundle size, tree-shaking) and distinguishes itself from sibling tools by noting the NPM-only scope and directing other ecosystems to deps.dev:version.

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 trigger phrases ('is X safe / popular / small', 'what does adding lodash cost me') and an explicit exclusion with an alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This is clear 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?

Despite annotations already indicating read-only, open-world, and idempotent behavior, the description adds substantial non-redundant detail: the exact embedding model (BGE-base-en), chunking method (500-char overlapping windows), scoring mechanism (cosine), output structure (character offsets and similarity scores), and the 200K character cap with truncation flagging. This goes well beyond the annotation hints and sets clear expectations for edge cases.

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

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

The description is well-structured with a front-loaded main purpose, followed by usage guidance and technical specifics. While it is slightly verbose in repeating the context-saving benefit, every sentence carries functional weight. It remains compact relative to the amount of behavioral detail conveyed.

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

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

No output schema is provided, so the description takes on full responsibility for explaining return values. It clearly states the output includes top-N passages with character offsets and similarity scores, and mentions the truncation flag for oversized inputs. This provides an agent with all necessary information to invoke the tool and interpret results confidently.

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

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

The schema already provides 100% parameter coverage with clear descriptions for text, query, and limit. The description reiterates the text source and query purpose, and notes 'top-N passages' which maps to limit, but adds limited new semantics beyond what the schema already provides. 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: 'Semantic search INSIDE a fetched record.' It provides concrete examples ('SEC 10-K body, an article, a long tool result') and explicitly differentiates from siblings by pairing it with ask_pipeworx_grounded. The verb 'search' and resource 'a fetched record' 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?

Guidance is explicit: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also names the complementary tool ask_pipeworx_grounded and explains how to combine them ('fetch with the gateway, ground over the relevant passages'), giving clear when-to-use and when-to-pair context.

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

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

Beyond the annotations, the description reveals significant behavioral details: anonymous/BYO accounts cannot persist subscriptions, SMS requires verified phone with a 10/day cap, webhook uses HMAC signing with a one-time secret, and webhook auto-disables after 10 consecutive failures. These are critical side effects and constraints 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?

The description is dense and technical but well-structured: purpose first, then return value, then auth requirement, then supported types with inline examples, then delivery channels. Each clause carries useful information, though the webhook segment is lengthy and could be split for readability.

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

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

Given the tool's complexity (5 subscription types, 3 delivery channels, nested objects, no output schema), the description covers all essential aspects: return value, required authentication, type-specific parameters, channel behaviors, limits, and security details. It leaves no major operational gap.

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

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

Although the schema already describes each parameter, the description significantly enriches semantics by providing concrete examples for every subscription type, detailing nested structures (e.g., items:["5.02"] for sec_8k, topic:"fed" for polymarket_edge), and specifying validation rules (E.164 format, verified phone, https-only webhook, localhost rejection). This goes far 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 opens with a precise verb-object pair ('Create a proactive monitoring subscription to a live-data event stream') and clearly states the return value ('Returns the new subscription id'). It enumerates specific subscription types, making the tool's purpose unambiguous even without comparing to sibling tools.

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

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

The description gives important preconditions (OAuth account requirement) and delivery channel options, but does not explicitly contrast with sibling tools like list_subscriptions or unsubscribe. An agent would infer use cases, but the description stops short of saying 'use this when you need to create, not list or delete subscriptions.'

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds useful behavioral context: returns category-bucketed examples from a live catalog, supports topic focusing, and mentions the exact tool+argument shape in the output. No contradictions, and the added context goes beyond safe-operation hints.

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

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

The description is a long single paragraph that begins with a list of example phrasings ('What can I ask Pipeworx? / ...') before stating the actual purpose after a dash. It is packed with useful information but not front-loaded; restructuring to put the core description first would improve clarity. The length is justified by content, but structure could be more concise.

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

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

For a tool with a single optional parameter and no output schema, the description is complete. It covers the return value (category-bucketed example questions with tool names and argument shapes), the optional parameter semantics, and the appropriate usage context. It even explains that results come from a live catalog, giving agents a full picture of what to expect.

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

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

The schema already documents the `topic` parameter at 100% coverage, so baseline is 3. The description enriches it with concrete examples ('finance', 'pharma', 'betting') and clarifies the optional behavior ('Omit for a cross-category spread'), adding meaning beyond the schema's field description.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions with the exact tool and argument shape needed to answer them. It positions itself as an onboarding entry point, distinguishing it from sibling tools by framing its role as discovering what Pipeworx can do.

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

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

Explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also provides invocation guidance: 'Call with no arguments for the full spread, or pass `topic` to focus,' and lists example topics. This is clear when-to-use guidance with reference 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?

Annotations already indicate non-destructive, idempotent behavior. The description goes beyond by disclosing ownership enforcement and the deactivation- instead-of-deletion semantics, tying historical data retention to recent_alerts. This adds meaningful operational 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?

Two front-loaded sentences, each earning its place. The core action and all critical caveats are stated without 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 one-parameter tool, the description covers the action, ownership restrictions, and data retention implications. It doesn't describe return values or error cases, but given the tool's simplicity and annotation coverage, it is sufficiently complete.

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

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

The schema fully covers the single id parameter, noting it as a UUID returned by subscribe. The description adds no new parameter-level information beyond restating 'by id', so it meets the baseline without extra value.

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 'Cancel a subscription by id', using a specific verb and resource, clearly distinguishing it from subscribe and list_subscriptions. It also clarifies the soft-delete behavior, reinforcing the exact action performed.

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 useful context: ownership is enforced, and historical events remain accessible via recent_alerts. However, it doesn't explicitly discuss when not to use or compare against alternatives like deleting permanently, but the context is clear enough for selection.

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

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

The description goes far beyond the annotations, explaining the two execution paths (SEC EDGAR fast path vs. grounded pipeline), the meaning of each return verdict, and the critical distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no coverage). It includes concrete warnings about not treating 'could_not_verify' as evidence, which is essential 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 every sentence contributes context: examples, usage, execution paths, return values, edge-case warnings, and pipeline replacement. It is longer than minimal but justified by the tool's complexity; still, it could be slightly more streamlined without losing value.

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

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

For a tool with no output schema, the description thoroughly covers return values (verdicts, actual value with citation, reasoning) and error semantics. It also addresses edge cases and default behaviors, making it complete for an agent to invoke and interpret results correctly.

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

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

The schema already has 100% coverage with descriptions for both parameters, so the baseline is 3. The description adds meaningful extra semantics for tolerance_pct, explaining how it overrides claim wording, caps at 5 by default, and suggesting values for hallucination detection. This enriches the parameter understanding beyond the schema.

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

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

The description uses specific verbs like 'verify' and 'fact check' with clear examples of natural-language claims, and explicitly states the tool's function: natural-language claim verification against authoritative sources. It distinguishes itself by describing the two verification paths and noting it replaces 4-6 sequential calls, which differentiates it from sibling tools like ask_pipeworx_grounded.

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

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

The description provides clear when-to-use context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also implies alternatives by noting it replaces multi-step pipelines, but it does not explicitly state when not to use it or name specific alternative tools, so it falls short of a 5.

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

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

Annotations already declare this as read-only, non-destructive, and idempotent. The description adds behavioral context by indicating it accepts any complaint and applies maximum Victorian indignation, giving a sense of the output tone. It does not describe output structure, but that is covered by the output schema.

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, using two punchy sentences that are memorable. However, it sacrifices functional detail for humor, so while it is efficient, it is not maximally informative.

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 five parameters and no schema descriptions, the description is far too thin to be complete. It does not specify how parameters influence output, what inputs are required beyond 'complaint', or any edge cases, making it inadequate for reliable 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?

With 0% schema description coverage, the burden falls entirely on the description, which does not explain any parameter. The agent is left guessing the meaning and effect of 'length', 'indignation', 'recipient', and 'complaint_type', making this dimension severely lacking.

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: transforming any complaint into an over-the-top Victorian-style expression of indignation. The example about slow wifi reinforces this purpose, and it is easily distinguished from all sibling tools, which are research/analytics oriented.

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?

No guidance is provided on when to use this tool, when not to use it, or alternatives. Although the tool is unique, the description lacks explicit usage scenarios or prerequisites, leaving the agent to infer applicability solely from the whimsical tone.

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