Librivox

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds valuable behavior beyond that: the default model (Workers AI free), the cost implication of using Anthropic ('you pay Anthropic directly'), and the exact return payload structure. It also notes the scoring range and combined view, providing full transparency for a probing tool.

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

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

The description is three sentences long, front-loading the core purpose, then briefly covering default behavior, output shape, and use cases. Every sentence carries information with no redundant filler.

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

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

Given there is no output schema, the description fully covers the return format (per-model {score, confidence, signals, raw_response} + combined view). It also explains the default model, API key requirement, and common use cases. For a read-only tool with strong annotations, this is complete.

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

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

Schema coverage is 100% with each of the 4 parameters clearly described (entity, models, _apiKey, context). The description adds marginal value by echoing the default model behavior and the BYO-key model, but the schema already covers these details, so the description does not significantly compensate beyond 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 opens with a specific verb 'Probe' and resource 'one or more LLMs', and explicitly states the output is a visibility score (0-100) per model. It clearly distinguishes from sibling tools like ask_pipeworx by framing the tool as a cross-LLM brand visibility checker, with use cases like AI-marketing audits.

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 it ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and when to pass the `_apiKey` to also probe Anthropic. It does not explicitly name alternative tools or exclusion criteria, but the purpose is specific enough to infer appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it routes to tools, fills arguments, returns stable pipeworx:// citation URIs, and works on every tier. This goes beyond 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?

The description is front-loaded with the key recommendation, structured logically into guidance, examples, alternatives, and exceptions. Every sentence adds value, and despite length, it remains scannable and purposeful.

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

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

For a tool that handles broad open-world questions, the description covers when to use, when not to use, examples, output characteristics (citations), and alternatives. It even addresses breaking news nuance. This is thorough for the tool's complexity.

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

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

Schema description coverage is 100% for the primary parameter and its aliases. The description's examples illustrate the range of questions but do not add syntax or format details beyond the schema, 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 the tool's purpose: it answers factual questions by routing to verified sources and returning structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by explaining when to step up to those alternatives.

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

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

Extremely explicit guidance: says to prefer over web search, gives start-here default positioning, provides examples of appropriate queries, and explicitly lists when to choose alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions, and handles breaking news itself).

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

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

The description goes beyond the annotations by disclosing the experimental nature, the current inactive state of candidates, the fact that it is a full working router with no fallback, and that results are compared against the stable router. This provides significant behavioral context not captured by readOnlyHint, openWorldHint, idempotentHint, or destructiveHint.

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 slightly verbose but every sentence contributes meaningful information about the beta status, current behavior, and usage. It is front-loaded with the key purpose and follows with necessary caveats. It earns a 4 for being detailed 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 complex beta tool with no output schema, the description covers the essential aspects: what it does, how it differs from the stable version, current state, usage instruction, and the fact that it returns the same response shape as ask_pipeworx. This is complete enough for an agent to correctly select and invoke the tool.

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

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

The input schema fully covers all parameters (100% coverage) with descriptions for each alias and the main 'question' parameter. The description adds that it uses the same arguments as ask_pipeworx, but this is minimal beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx with the same universal routing capabilities, and explicitly differentiates it from the stable sibling by highlighting the experimental candidate routing improvements. It states the specific verb ('asks') and resource (Pipeworx router) with clarity.

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

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

It provides a clear usage context: use when you want the newest routing, and notes that it currently matches ask_pipeworx exactly. It does not explicitly mention exclusions or alternative stable tools, but the beta vs. stable distinction is implicit in the description and sibling list.

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

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

Beyond the readOnly/idempotent annotations, the description reveals the full refusal mechanism with exact refusal_reason values, the success return shape (answer, evidence, confidence, source, etc.), and the strict grounding behavior (no invention from outside the tool result). It also discloses the extra LLM call cost, which is critical 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?

The description is dense but every sentence earns its place: core value proposition, mechanism, return format, refusal reasons, use cases, and cost tradeoff. It is front-loaded with the key concept and structured to move from high-level purpose to precise behavioral details without fluff.

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

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

With no output schema, the description fully specifies both success and failure response shapes, including the refusal_reason enum and data types. It also provides routing scale (5,529 tools across 1455 sources) and cost implications, making the tool's behavior entirely predictable for an agent.

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

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

The input schema covers 100% of parameters with explicit descriptions for all aliases, so the baseline of 3 applies. The description adds no extra parameter-level semantics beyond confirming natural language input, which is already in the schema.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It explicitly distinguishes itself from sibling ask_pipeworx by adding grounded extraction (using ONLY what the tool result contains) and evidence quoting. This is a specific verb+resource with clear differentiation.

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

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

The description gives explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on') and when-not-to-use ('prefer ask_pipeworx for casual lookups'). It also notes the cost tradeoff (one extra LLM call), helping the agent choose appropriately between siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds no additional behavioral context beyond the fact that it operates by ID, which is already captured in the 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 a single, short phrase that is concise and front-loaded. It contains no wasted words and effectively communicates the tool's scope for a simple lookup operation.

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

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

Given the tool's simplicity (one required ID param), rich annotations, and the presence of an output schema, the description adequately covers core functionality. It does not discuss error cases or return details, but those are likely covered by the output schema and the straightforward nature of the operation.

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

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

The schema has a single 'id' parameter with no description. The description mentions 'by id', providing the semantic meaning that this is an audiobook identifier, which partially compensates for the 0% schema description coverage. However, it does not elaborate on the parameter's format or constraints.

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

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

The description clearly identifies the resource (audiobook) and specifies it returns a single item by ID, distinguishing it from the sibling 'audiobooks' (plural). However, it lacks an explicit verb like 'get' or 'fetch', making the operation slightly implicit.

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 explicit guidance is given on when to use this tool versus alternatives like 'audiobooks'. The singular/plural naming implies use when an ID is available, but the agent must infer this context without direct instruction.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value beyond annotations by disclosing pagination support (limit/offset) and the return fields (reader, language, URL, chapter count). It provides useful behavioral context without contradicting any annotation.

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

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

The description is two well-structured sentences, front-loaded with the primary action and criteria, followed by return metadata. Every phrase earns its place with no filler or repetition of schema details.

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

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

For a search tool with six optional parameters and an output schema, the description covers the core search criteria, pagination, and return content. It does not explain the query/title distinction but is otherwise complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is only 33%, so the description carries extra weight. It explains the purpose of 'author', 'since', 'limit', 'offset', and 'query' (as title keyword), but leaves ambiguity between 'query' and 'title', and does not explicitly mention the 'offset' parameter name. It compensates partially but not fully.

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

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

The description states the exact action ('Search LibriVox free public-domain audiobooks') and specifies the search criteria (title keyword, author name, date added). It clearly distinguishes this from the sibling 'audiobook' tool by focusing on search rather than singular access, 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?

The description conveys clear usage context: use this tool to search for audiobooks by title, author, or date, with pagination. It does not explicitly name alternatives or exclusions, but the search-focused wording and sibling context imply when to choose it over the singular 'audiobook' retrieval tool.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds pagination support and return format, but does not disclose behavioral caveats such as result limits or open-world completeness. 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?

Two tightly structured sentences: one for functionality, one for return values. No redundant or extraneous content, and key details are 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?

With annotations and an output schema, the description provides adequate context for invoking the tool. It could add more on parameter ranges or usage scenarios, but it is complete enough for a simple search tool.

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

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

Schema has zero description coverage, but the description compensates by mapping query and last_name to search criteria and limit/offset to pagination, covering all four parameters. It does not detail constraints or combinations, but provides sufficient 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?

Description states 'Search LibriVox authors' with specific search criteria (last name, keyword) and returns (id, name, profile link), clearly distinguishing it from sibling tools like audiobooks or tracks.

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 explicit when-to-use or alternative guidance is provided. The usage is implied by the clear purpose, but the description does not contrast with other lookup tools or mention 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 only declare read-only/idempotent. The description goes far beyond: resolver contract with market_match_confidence, parent_event extractor, news fallback fields, low_confidence_match short-circuit, market_closed_or_inactive status, tradeability flag, and cancellation-rule risk. This is exceptional disclosure.

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

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

Long but every section adds operational value; organized with SCREAMING labels and inline examples. Front-loaded with purpose; 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?

No output schema exists, but description specifies response shape (result.market/analysis/evidence), resolver contract, parent event, news fields, and edge cases. For a high-complexity research tool with 3 params and rich behavior, this is comprehensive.

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

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

Schema covers all 3 params with descriptions. Description adds accepted input formats, quick vs thorough fan-out semantics, and include_raw size consequences, enriching the schema 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?

First sentence states it researches a Polymarket bet by pulling Pipeworx data in one call, resolves/classifies and returns an evidence packet plus comparison. This clearly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly gives use cases ('Use for "should I bet on X"...') and explains blocking routes for low-confidence/closed matches. However, it doesn't name alternatives or say when to prefer polymarket_edges/arbitrage, so not 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 indicate a safe read-only, idempotent operation. The description goes beyond by explaining data sources (SEC EDGAR/XBRL, FAERS, FDA), special handling of off-calendar fiscal years, sorting behavior, and that results include paired data + citation URIs. This adds rich context 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 dense but every sentence earns its place. It front-loads trigger phrases and purpose, then systematically explains type-specific behavior, sorting, and output format. There is no fluff or redundancy; it's a well-structured, information-rich paragraph.

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 and the absence of an output schema, the description covers all critical aspects: when to use, what it does, per-type data sources, sorting, return format, and even a performance note (replaces 8–15 sequential lookups). The agent has enough context to invoke it correctly without needing additional clarification.

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

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

Schema coverage is 100%, but the description adds meaning by explaining what each type parameter does (company pulls financial metrics, drug pulls adverse-event and trial counts) and provides concrete examples for the values array. This goes well beyond the schema's own parameter descriptions.

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

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

The description opens with explicit trigger phrases and states the core function: "side-by-side comparison of 2–5 companies or drugs in ONE parallel call." It clearly distinguishes from siblings by saying "ALWAYS PREFER over sequential single-pack lookups when comparing entities," making it unambiguous when this tool is the right choice.

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 through trigger phrases and a strong directive to prefer this tool over sequential single-pack lookups. It also clarifies what each type ('company' vs 'drug') retrieves, giving the agent enough context to decide when this tool is appropriate versus alternatives.

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

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

Annotations declare readOnly, openWorld, idempotent, and destructive=false, but the description goes far beyond: paid plan requirement for 'thorough', latency expectations (15-60s, ~90s for thorough), citation fetchability rules, never-invented gaps[], contradiction scanning, and semantic excerpting behavior. No contradiction with annotations.

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

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

The description is long, but each sentence covers a distinct, essential aspect (access, alternatives, mechanism, output format, use cases, depth behavior, latency). It is front-loaded with the account requirement and never repeats schema verbatim. It is somewhat dense, but justified for the tool's complexity.

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

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

With no output schema, the description fully explains the return packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[]), edge cases (empty gaps for topics not in the structured catalog), depth-specific recovery behavior, and prerequisites. Nothing critical is left unexplained.

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

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

Both parameters are already described in the schema (100% coverage), giving a baseline of 3. The description adds meaningful parameter context not in schema: depth:'thorough' requires a paid plan and latency grows with depth, plus it reinforces that the question can be broad/multi-part. This pushes it 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 clearly identifies a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly contrasts itself with open-web search. It differentiates from siblings by naming ask_pipeworx as the alternative and describing deep_research's batch/parallel nature.

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

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

Explicit when/when-not guidance is provided: 'For a single lookup use ask_pipeworx (one LLM call, not many)', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and the account fallback 'If you are not signed in, use ask_pipeworx instead'. It also states best-fit scenarios like 'Best for broad/multi-part questions over structured data'.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses the return format: top-N tools with names, descriptions, full schemas, and curated examples, and that results are directly callable without further lookup. This adds useful behavioral context about output and integration.

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, then listing domains and return behavior. While the domain list is lengthy, it is informative and each sentence earns its place. Slight redundancy with schema examples exists, but overall structure is efficient.

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

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

For a discovery tool with no output schema, the description compensates well by explaining what is returned (names, descriptions, schemas, examples) and when to use it first. It covers usage context and result readiness, making it largely complete despite minor omissions like error behavior.

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

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

Schema coverage is 100% with descriptions for all parameters, including aliases. The description adds only minimal semantic value (e.g., 'describing the data or task') but does not detail parameter formats or edge cases beyond the schema, aligning with the baseline 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 states the verb+resource: 'Find tools by describing the data or task.' It distinguishes itself from siblings by specifying its role as a discovery meta-tool ('Call this FIRST when you have many tools available') and gives a concrete list of covered domains, 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?

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available...' providing clear context for when to invoke. It lacks explicit when-not conditions or named alternatives, but the 'not just one answer' phrase adds nuance.

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 adds meaningful behavioral context: it fans out across multiple sources, soft-fails on the patents API due to sunset, and details the exact return structure with URIs and field specifics. This exceeds the annotation-provided safety profile.

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

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

The description is dense and well-structured, leading with user query examples, then usage guidance, then return details. The list of example phrases is slightly redundant but each adds value in clarifying intent, and no information is extraneous.

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 compensates by listing every returned component (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and even notes the soft-fail behavior. This makes the tool's behavior and outcomes highly predictable 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 the schema covers both parameters (type and value), the description enriches them significantly by specifying the exact accepted formats: zero-padded CIK, ticker examples, and explicitly stating that names are not supported. This goes well beyond the baseline schema descriptions.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and gives multiple user query examples ('Tell me about X', 'research Acme'), making the purpose unmistakable. It also distinguishes itself from chaining single-pack lookups, a clear differentiator.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' offering direct when-to-use guidance. It also specifies when not to use it (names not supported) and directs to resolve_entity first, providing clear 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 destructiveHint=true and idempotentHint=true. The description adds context about the purpose of deletion, such as clearing sensitive data and handling stale context, which goes beyond the annotation details 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?

Two sentences, front-loaded with the action and resource. Every clause contributes value: the purpose, usage scenarios, and tool pairing. No redundancy or irrelevant 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?

For a low-complexity tool with one parameter and no output schema, this description is complete. It explains what the tool does, when to use it, and its relationship to sibling tools, including the specific use case of clearing sensitive data.

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

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

Schema coverage is 100%, with the single 'key' parameter described as 'Memory key to delete'. The description adds that the memory was 'previously stored' and associates it with remember/recall, but does not provide additional syntax or format details beyond what the schema already contains.

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

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

The description explicitly states 'Delete a previously stored memory by key', using a specific verb and resource. It clearly distinguishes this tool from siblings like remember and recall by being the deletion counterpart.

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 conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data...'. Also mentions pairing with remember and recall, giving clear guidance on alternatives and complementary 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 details the process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format') and the output ('single text blob ready to drop at site-root/llms.txt'). Annotations already declare readOnlyHint and idempotentHint, so the description adds operational context 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?

The description is three sentences, each serving a distinct role: purpose, process/output, and use cases. It is concise and front-loaded, with every sentence contributing 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?

Even without an output schema, the description explains the return type ('single text blob') and the general format (standard llms.txt markdown). It covers multiple use cases and the operational flow, making it complete 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 has 100% description coverage for both parameters (url and max_links), so the description does not need to add parameter-level details. It supports the tool's purpose but does not explain parameter behavior beyond what the schema already conveys.

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: 'Generate a production-ready llms.txt file for any URL,' which clearly defines the tool's action and target. It also mentions the intended audience (AI crawlers) and distinguishes itself from sibling tools by focusing on generating the file rather than just analyzing visibility.

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 lists three concrete 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.' This provides clear context for when to use the tool, though it does not explicitly name alternative tools for exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds meaningful context: it scopes to the caller's subscriptions, mentions the default exclusion of inactive ones, and lists the return fields. 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 two sentences, front-loaded with the main action and the return payload, followed by a clear usage note. 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 read-only list with one optional parameter and no output schema, the description covers purpose, return fields, and usage. It is complete for an agent to invoke correctly and understand the response.

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

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

The single parameter include_inactive is fully described in the input schema (default false and what it does). The tool description does not add extra parameter semantics, so baseline 3 applies due to 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 specifies the action (list), the resource (the caller's active subscriptions), and the returned fields (id, type, params, etc.). It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing only.

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 use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It does not name alternatives explicitly but implies them (subscribe/unsubscribe). No exclusions are given, but the context is clear enough for an agent to choose this tool appropriately.

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 important behavioral traits not visible in annotations (which are all false and thus uninformative): the claim_token flow (filing returns a token, passing it later reads status), rate limiting ('5 per identifier per day'), that it's free and doesn't count against quota, and that the team reads digests daily and signals affect roadmap. It also advises against pasting the end-user's prompt, which is a nuance that helps the agent act appropriately.

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

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

The description is longer than average but every sentence adds value: purpose, usage triggers, scoping restrictions, content guidance, token mechanism, rate limits, and quota impact. It is front-loaded with the core purpose and structured logically. It could be tightened slightly, but it avoids redundancy and fluff, making it effective despite its length.

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

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

Despite having no output schema, the description fully covers the tool's behavior: what happens on filing (returns claim_token), how to retrieve resolution status, rate limits, quota impact, and content requirements. It also addresses edge cases (feedback about non-Pipeworx tools, uncertainty about which tools are Pipeworx). For a feedback tool with nested context objects and multiple optional params, this is exceptionally 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?

Input schema already covers all 4 parameters with detailed descriptions (100% coverage), so baseline is 3. The description adds meaningful context beyond the schema, specifically explaining the claim_token usage pattern ('Filing without an account returns a claim_token; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and emphasizing that feedback should be described in terms of Pipeworx tools/packs. This elevates it above baseline but doesn't enumerate all parameters, so not a 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 opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates specific categories (bug, feature/data_gap, praise) which clearly distinguishes it from sibling research tools like ask_pipeworx or deep_research. It also explicitly scopes the tool to feedback about Pipeworx tools only, differentiating it from any other MCP server feedback paths.

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

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

Explicit 'Use when' conditions are provided for each feedback type: bug (wrong/stale data), feature/data_gap (missing tool), and praise. It also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead,' plus a disambiguation tip ('Not sure? Pipeworx tool names are the ones this connection lists'). This is far beyond a basic usage hint.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable context: it is self-aggregating, derived from CF analytics-engine, contains no PII (just pack, tool, count), and is cached for 5min-1h depending on the window. This goes beyond the annotations and explains the 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 compact (4 sentences) and front-loaded with the core purpose. Each sentence adds value: main function, return contents, use cases, and behavior notes. There is no fluff or repetition of structural 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?

Despite lacking an output schema, the description clearly lists what is returned (top tools, top packs, total call volume) and explains the data source, privacy, and caching. Given the tool's simplicity (one optional param with enums), the description fully covers the agent's needs for selection and invocation.

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

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

Schema coverage is 100% for the single 'window' parameter, and the schema description already explains the meaning of each enum value. The tool description mentions the windows and adds a brief explanation about shorter vs longer windows, but that meaning is largely duplicated from the schema. Baseline of 3 applies when 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 opens with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now.' It then details exactly what is returned (top tools, top packs, total call volume) and the time windows. This distinguishes it from siblings like discover_tools or recent_alerts by focusing on aggregate trending call data.

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

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

The description explicitly lists three use cases (e.g., 'discovering what data sources are hot for current events', 'confirming a popular tool is the canonical choice before asking your own question'). It provides clear context for when to use it, though it does not name alternative tools or state when not to use it.

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

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

Despite annotations already indicating read-only/idempotent behavior, the description adds substantial context: explains partition-check math (sum of YES prices ≈1), threshold for signals (>3pp), placeholder filtering (20% rule), and fill-check logic (realizable_edge_pp ≤ 0 means don't trade). It also reveals skipped_low_similarity rejection counts. No contradictions with annotations.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. It packs dense information with no fluff, but the length is near the upper limit for a tool description, so a 4 is appropriate.

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

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

With no output schema, the description compensates fully by detailing the response shape: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and partition_check fields. It also explains edge cases like skipped_low_similarity and placeholder fractions, and the fill-check behavior, making it complete for a complex tool.

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

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

Schema coverage is 100%, but the description enriches both params significantly: `event` is described as walking child markets and checking ordering plus partition sum; `topic` is described as searching related events and flattening markets. It also notes that `event` accepts full URLs, adding usability detail beyond schema.

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

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

The description clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies distinct modes (`event`, `topic`, and default `trending_scan`) and gives concrete examples. This distinguishes it from sibling tools like `polymarket_edges` or `polymarket_fill_risk` by naming the exact methodology.

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: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also recommends `event` for specific markets and `topic` for cross-event scanning, and directs users to `polymarket_fill_risk` for custom sizing, showing clear alternative handling.

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. It discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), output structure (_diagnostics with funnel counters), edge interpretation ('your edge may already be in the price'), model-specific caveats (e.g., news_momentum 'soft signal w/ halved Kelly'), and parameter interactions. This is rich behavioral context that no annotation conveys. Annotations are readOnly, idempotent, non-destructive, and the description does not contradict them.

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

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

The description is information-dense but poorly structured for quick consumption. It is a single massive block of text with inline parentheticals covering model specifics (e.g., α values for tennis/soccer/MMA), placeholder-filter examples, and response segments. While every sentence carries some information, it is over-specified for the purpose of tool selection and invocation. It could be broken into clear sections (e.g., 'Segments', 'Knobs', 'Response') with less verbose technical detail. It's adequate but not concise.

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

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

Given no output schema, the description fully carries the burden of explaining return values. It details the top-level response (_by_segment, fed_candidates/fed_note, _diagnostics) and explicitly explains how to interpret empty segments ('funnel counters, category_counts, filter_skips so callers can see WHY a segment is empty'). It also covers knobs, caching, and known limitations. For a 9-parameter, complex tool with no output schema, the description is exceptionally 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 the baseline is 3. The description adds value by explaining the interplay and rationale of knobs, e.g., 'TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable' and the critical detail that 'Partition arbs always return kelly_fraction_half=0 at the parent level... so min_kelly never filters them — this knob applies to the per-leg Kelly inside top_legs instead.' This is not present in the schema's parameter description and meaningfully enhances the agent's understanding.

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

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

The description opens with a specific verb-resource combination: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It immediately conveys the tool's unique scope and distinguishes it via the Pipeworx data comparison, model-family segments, and the 'what should I bet on today' use case. This is far beyond a tautology or vague 'processes data' statement.

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

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

It provides clear context for when to use the tool ('Built for "what should I bet on today"') and includes explicit when-not behavior, such as excluding Fed bets ('1m-T vs EFFR signal is unreliable at meeting-month horizons') and dropping placeholder-slug partitions. However, it does not name alternative sibling tools (e.g., polymarket_arbitrage) or explicitly say 'use this instead of X', so it stops short of a full alternatives comparison.

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 (readOnlyHint, idempotentHint, etc.) by disclosing behavioral nuances: snapshots are written only when polymarket_edges runs on a cache-miss, so gaps mean no scan happened; history is bounded by a 60-day TTL; decay uses daily closes of edge_pp_net; expired opportunities include lifespan data. This gives an agent a realistic model of data freshness and caveats. No contradiction with annotations.

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

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

The description is long but well-structured with ARGS, RESPONSE, and LIMITS sections. Every sentence carries distinct information, and the use of inline examples (trend values, decay formula) makes it density-efficient. It loses a point for length, but the structure keeps it navigable.

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 explains the response shape (tracked, expired, snapshot_dates), interprets key fields (trend, decay_pp_per_day), and covers limitations (TTL, cache-miss gaps, daily closes). This is unusually complete for a read-only telemetry tool, covering data provenance, edge cases, and interpretative guidance.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds a bit of context by labeling 'window' as a 'snapshot family' and indicating defaults, but this mostly repeats schema info. The extra framing of 'window family' helps differentiate the snapshot groups, adding modest value beyond the schema.

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

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

The description clearly states it provides 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. This goes beyond the generic title and distinguishes the tool from the sibling 'polymarket_edges' by focusing on historical persistence/decay rather than current edge values.

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

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

It explains when the tool is valuable: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take)' and notes the 'median lifespan is your competition clock'. While there is no explicit 'use instead of X', the context strongly implies use cases and even hints at a core decision framework. No clear exclusions or alternatives are stated, but the guidance is substantial.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. The description adds depth by detailing that it 'walks the ladder,' returns specific fill metrics and a verdict, and warns about partial basket fills converting an arb into an unhedged directional position. There is no contradiction with annotations.

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

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

The description is long but densely informative, structured into single-market and basket blocks with a clear usage call-out. Every sentence adds functional detail, and it is front-loaded with a one-line summary of the tool's core purpose.

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

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

With no output schema, the description compensates by listing all major return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) for single-market and a full set for basket mode (theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, etc.). It also covers edge cases like thin books and forced directional risk, making it contextually 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?

All 4 parameters have schema descriptions (100% coverage), so baseline is 3. The tool description adds meaning by explaining dual interpretation of size_usd (spend on buys vs proceeds on sells vs settlement notional) and side default logic in basket mode, going beyond the schema. This extra context earns a 4.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a specific verb+resource statement. It clearly distinguishes single-market and basket modes and lists distinct outputs for each, differentiating it from sibling arb/edge 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 explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why theoretical overround is not capturable. It also contrasts single-market vs basket usage internally, providing clear when-to-use guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds significant behavioral detail: compatibility_warning conditions for non-equivalent bet shapes, temporal_alignment semantics, and skipped_cross_type/subtype counters. It explains what the tool does in edge cases and what the response fields mean, which is far beyond the annotation baseline. No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Every sentence contributes important information, though a few clauses could be tightened (e.g., the final caution is repeated in spirit). Overall it's appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (two venues, two modes, compatibility warnings, no output schema), the description covers the essential semantics: response fields (prices, spread, top_spreads_pp), safety flags (compatibility_warning, temporal_alignment, skipped_cross_type), and limitations. It provides enough context for an agent to understand when results are meaningful and when they are not, making it complete 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?

The schema already provides 100% coverage, listing all three parameters with descriptions, so baseline is 3. The description adds value by explaining the topic shortcuts in full, providing concrete examples for kalshi_event_ticker and polymarket_event_slug, and clarifying that explicit tickers override the topic-mapped side. This extra context justifies a 4 rather than a 3.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly explains the tool's function and mentions the key distinction that the spread is meaningful only when bet shapes are equivalent. However, it doesn't explicitly distinguish from sibling tools like polymarket_arbitrage or polymarket_edges, so it misses the 'distinguishes from siblings' bar for a 5.

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

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

The description provides clear context on how to invoke the tool: two modes (topic shortcuts or explicit tickers) with explicit examples for each. It also warns that pre-mapped topics often return compatibility warnings, implying when the tool may not produce a tradeable signal. However, it never directly says when to use this tool versus alternatives, nor does it list exclusions beyond the inherent compatibility caveats.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds specific context about scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the ability to list all keys by omitting the key argument, which go beyond the annotation fields and provide useful behavioral detail.

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

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

Three sentences, each earning its place: function, usage rationale, and scope/pairing. No redundant or filler content, and the most critical information is front-loaded in the first sentence.

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-optional-param read tool with strong annotations, the description is complete: it explains what it returns (value or list of keys), how to use it, and its scope. Despite no output schema, the description adequately conveys the return behavior without needing explicit structure, making it sufficient for an agent to invoke correctly.

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

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

The schema covers the 'key' parameter with a description that matches the behavior. The description adds semantic detail by giving examples of what keys may represent (user's target ticker, address, research notes) and reiterates the omit-to-list behavior, enhancing understanding beyond the schema without repeating it verbatim.

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 'Retrieve' and 'list all saved keys', clearly identifying the tool's function as reading from a memory store. It also explicitly references siblings 'remember' and 'forget', distinguishing its role as the read operation among them.

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

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

It states 'Use to look up context the agent stored earlier' and explicitly pairs with 'remember to save, forget to delete', providing clear when-to-use and alternative tools. The scoping note also informs about identifier-based access, helping the agent decide when this tool is appropriate.

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

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

The description states that setting mark_read:true will 'flag returned events read so the next call only shows newer ones,' implying a persistent state change. This directly contradicts the annotation readOnlyHint=true. The description adds useful behavioral context, but the contradiction is a critical flaw, making transparency score 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 four sentences, effectively front-loaded with the main purpose, followed by useful details about return payload, filtering, mark_read, and an HTTP alternative. The HTTP sentence is slightly tangential but still concise and relevant.

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

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

The description covers the return payload, filtering, mark_read behavior, polling suitability, and an alternative access method. Combined with the detailed schema, it provides a fairly complete picture for a read-oriented tool, though the mark_read contradiction is a significant gap that prevents a higher 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?

Schema coverage is 100%, so the baseline is 3. The description adds an example for type ('sec_8k') and clarifies the consequence of mark_read on subsequent calls, which goes beyond the schema's descriptions. This enriches parameter meaning.

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

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

The description clearly identifies the tool as fetching 'fired events from your subscription feed' and specifies what is returned (recent alerts with source, citation_uri, and raw event payload). This distinct verb+resource combination differentiates it from sibling tools like list_subscriptions.

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

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

It explains how to filter by type and since, and provides contexts where polling is appropriate. The mention of the same feed via HTTP serves as an alternative for scripts/dashboards, giving clear usage context. However, it does not explicitly state when not to use this tool or contrast it with specific sibling tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, but the description adds substantial behavioral context: fan-out to multiple external APIs, fallback logic (GDELT preferred, GNews on rate-limit/5xx), and a soft-fail for USPTO due to PatentsView sunset. It also discloses the return structure (changes[], total_changes, pipeworx:// URIs), which is beyond what annotations provide.

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

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

The description is information-dense and well-structured, front-loading with user-intent phrases and then methodically covering sources, parameter format, return structure, and alternative. Though lengthy, every sentence contributes; the length is justified by the tool's multi-source complexity. It avoids redundancy with the schema, making it efficient for its scope.

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

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

With no output schema, the description compensates by describing the return format ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It covers edge cases like PatentsView sunset and GNews fallback, and clearly delineates when to use entity_profile. For a complex fan-out tool, this is complete and self-sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value for `since` by giving explicit formats and examples ('2026-04-01', '7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring. It also reinforces that `value` accepts ticker or zero-padded CIK, matching the schema but providing applied context.

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

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

The description opens with concrete user-intent phrasing ('What's new with X' / 'updates on Acme') and then states it is a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It goes on to enumerate specific sources (SEC EDGAR, GDELT→GNews, USPTO), which distinguishes it from sibling entity_profile (static profile). This is a specific verb+resource with clear differentiation.

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

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

The description provides example queries and explicitly names an alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also advises on typical usage with 'Use "30d" or "1m" for typical monitoring,' and explains when to expect fallbacks (GDELT→GNews on rate-limit/5xx). This is explicit when-to-use and alternative guidance.

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

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

Annotations already indicate write (readOnlyHint false), idempotent (idempotentHint true), and non-destructive (destructiveHint false). The description adds valuable context: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. This exceeds annotation coverage without contradiction. Slight gap: no mention of overwrite behavior or return value, but idempotent hint implies overwrite.

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

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

The description is three sentences, front-loaded with the primary purpose. Every sentence earns its place: purpose, usage guidance, and storage/persistence details. 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 two-parameter tool with rich annotations and 100% schema coverage, the description covers purpose, use cases, persistence, scoping, and sibling relationships. It lacks an output schema, but no return-value explanation is expected for such a straightforward write operation. The description is 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?

Schema coverage is 100% with clear descriptions for both key and value, so the baseline is 3. The description adds examples of use ('a resolved ticker, a target address...') that reinforce but do not significantly extend the schema's meaning. The key-value scoping is mentioned but already implied by the schema.

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

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

The description opens with a clear, specific verb and resource: 'Save data the agent will need to reuse later.' It distinguishes itself from siblings by explicitly pairing with recall and forget, and clarifies cross-session scope. The purpose is unmistakable and well-differentiated.

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

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

It provides explicit guidance on when to use: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference). It also explains persistence differences (authenticated vs anonymous) and names complementary tools, making the alternative usage 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?

Beyond annotations (readOnly, openWorld, idempotent), the description discloses that 'each call cascades through several lookup endpoints internally,' that LEI/FIGI enrichment degrades gracefully if sources are unavailable, and that unresolved identifiers are 'stated explicitly under `unresolved` rather than omitted.' These are meaningful behavioral insights not captured 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 long but well-structured, starting with example queries, then purpose, then supported types with specific details. Some example queries are redundant, but every sentence conveys operational value, so it's not wasteful.

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

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

For a tool with no output schema, the description compensates by detailing the output identifiers for each type, the source-labeling behavior, and the `unresolved` field. It also covers input variations and failure behavior, making it complete enough for an agent to invoke correctly.

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

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

The schema already fully describes both parameters (enum for type, formats for value). The description adds semantic depth by explaining what each type resolves to (e.g., company returns CIK + ticker + LEI + FIGI, drug returns RxCUI + ingredient + brand) and the graceful degradation behavior, which helps the agent choose correct inputs.

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 concrete user queries and states a specific verb: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also distinguishes from siblings by positioning itself as the prerequisite ID resolver ('Use FIRST whenever you have a name but need an ID').

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 with 'Use FIRST whenever you have a name but need an ID,' and explains that it 'replaces 2-3 manual lookups,' making it the clear choice over other tools. The directive is strong and actionable, even without an explicit when-not-to-use clause.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description doesn't need to restate those. It adds valuable process detail: probes each entity with ai_visibility_check, ranks results, and describes the return format (ranked list with score, confidence, signal density). This goes beyond 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?

The description is three sentences, front-loaded with the primary action, and every sentence earns its place. It includes a concrete example and return format without fluff, making it highly efficient.

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

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

For a read-only comparative tool with 4 parameters and no output schema, the description is complete: it explains the process, the output structure, and a concrete use case. The schema handles parameter constraints (2-8 entities, optional models), and annotations cover safety. No meaningful gaps remain.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds minimal extra meaning—mainly that context is applied to every probe and that ai_visibility_check is used for each entity. It doesn't elaborate on the 'models' or '_apiKey' parameters beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Compare') and identifies the resource ('AI visibility across multiple entities'), clearly distinguishing it from the sibling ai_visibility_check which handles single entities. It states exactly what it does: probes each entity, ranks by score, and surfaces the most/least recognized.

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

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

It provides a clear use case ('competitive AI-marketing audits') with an example query. While it doesn't explicitly name alternatives or exclusions, the comparison to ai_visibility_check is implied and the context is sufficient 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?

The description discloses behavior beyond the annotations: it's a composite of deps.dev and bundlephobia, handles partial failures gracefully, notes that the first bundlephobia measurement can take 5-30s, and mentions the sources_failed field. These runtime behaviors are not evident from 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 five dense sentences, each earning its place: purpose, use cases, output structure, ecosystem limitation, and failure behavior. It front-loads the core purpose and avoids filler. Despite length, it remains well-structured and information-dense for a complex composite 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 enumerating return fields (summary block with is_latest, license, advisory_count, bundle sizes, etc.), per-advisory details, links, and alternative versions. It also covers ecosystem scope and partial failure behavior, giving an agent everything needed to invoke and interpret results correctly.

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

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

Schema coverage is 100%: both 'package' and 'version' are described in the schema. The description adds no new parameter-level details; it only restates that 'package' is an npm package name and 'version' defaults to latest. Since the schema already provides full parameter semantics, 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 states a specific composite check for 'should I add this npm package to my project', listing concrete data points (license, advisories, bundle size). It clearly distinguishes itself from sibling tools like scan_competitor_ai_presence by naming its specific domain (npm dependencies) and the output format.

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

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

Provides explicit triggers: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an exclusion—'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'—and names the alternative. 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?

Goes well beyond the readOnly/idempotent annotations by revealing the embedding model (BGE-base-en), similarity metric (cosine), text window size (500-char overlapping), input cap (200K chars, truncation flagged), and return payload (character offsets, similarity scores). No contradiction with annotations.

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

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

The description is long but every sentence contributes value: purpose, use case, pairing, technical details, and limitations. It is front-loaded with the core action and structured logically. No fluff or redundancy.

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

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

With no output schema, the description adequately explains return values (top-N passages with character offsets and similarity scores). It also covers operational constraints (200K character cap, truncation flag) and provides enough context for an agent to invoke it correctly in a retrieval pipeline.

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 provides detailed descriptions for each parameter with examples. The tool description adds minimal parameter-specific meaning beyond reinforcing that text is 'already pulled' and query is natural language. It does not systematically elaborate on limit or further 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 precise verb+resource+scope: 'Semantic search INSIDE a fetched record.' It explicitly differentiates from sibling tools like ask_pipeworx_grounded by emphasizing it operates on already-fetched text, not the whole document or external 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?

Clearly states when to use: 'Use when the record is too big to cram into the prompt.' It also provides an explicit alternative/complement: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

The description adds meaningful behavioral context beyond annotations: it discloses that the tool returns the new subscription id, requires an OAuth account, and notes SMS phone verification and a 10/day cap. It does not mention idempotent deduplication (covered by idempotentHint) or webhook delivery auto-disabling, but the annotations and schema supply some of that context.

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

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

The description is front-loaded with the purpose and packs many useful details and examples into a few sentences. It is dense but still scannable; a bulleted list might improve readability, but the structure is acceptable and each clause earns its place.

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

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

The description covers return value, auth requirements, three subscription types, and two delivery channels. It omits patent_grant and clinical_trial from the supported types list and doesn't mention the webhook delivery option in prose, though the schema fills these gaps. Given the tool's complexity and no output schema, this is a moderate shortfall in completeness.

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 enriches semantics with concrete examples like items:['5.02'] = officer change and delivery channel configs. It also clarifies the always-on feed behavior. However, it only discusses three of the five enum types, relying on schema for patent_grant and clinical_trial.

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 'Create a proactive monitoring subscription to a live-data event stream,' which clearly identifies the verb, resource, and intent. It distinguishes this from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation of a persistent monitoring subscription.

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 prerequisites: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)' and mentions an alternative for pull-based access: 'pull via recent_alerts or GET registry.pipeworx.io/alerts.json'. However, it doesn't explicitly mention list_subscriptions as the way to view existing subscriptions, so the guidance is strong but not fully comprehensive.

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

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

Annotations already declare readOnly/idempotent/openWorld and non-destructive. The description adds valuable behavioral context beyond that: it returns category-bucketed example questions, includes exact tool + argument shapes, and can either return a full spread or focused results based on topic. This enriches the agent's understanding of the output and invocation semantics.

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 fairly long but every sentence contributes: it opens with natural language queries, defines the purpose, describes the return payload, and gives usage guidance. It is front-loaded with what the agent would ask, and the length is justified by the onboarding role. No fluff or repetition exists.

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 effectively complements the structured data by explaining what the tool returns (category-bucketed example questions with tool+argument shapes). It covers invocation modes (no args vs. topic) and the primary use case, making the tool fully understandable for an agent. The 1 optional parameter and annotations are simple, so the description provides complete context.

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

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

The schema covers the single optional parameter 'topic' with description, giving 100% coverage. The description adds extra meaning by listing example topic values ('finance', 'pharma', 'betting') and explaining the effect of omitting vs. providing the topic. This goes beyond the schema's bare enumeration, earning a score 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 clearly states the tool's purpose: it is the onboarding entry point for a newly connected agent to discover what Pipeworx can do. It specifies the verb (suggest/return example questions) and resource (category-bucketed examples from the live tool catalog), while distinguishing it from siblings like discover_tools by emphasizing the exact tool + argument shape returned.

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

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

Explicit usage guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also explains when to call with no arguments vs. passing a topic, and references meta-tools as alternatives. This clearly differentiates from sibling tools and gives actionable when-to-use.

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 safety profile is clear. The description adds that each track includes specific fields and a direct MP3 URL, which is useful behavioral context about the return data. However, it does not disclose any edge cases, authentication requirements, or rate limiting, leaving the description slightly below the level of rich behavioral explanation.

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 the core purpose in the first sentence and detail in the following two. It is well-structured and front-loaded, with no redundant filler. Each sentence contributes to understanding.

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 only one parameter, clear annotations, and an output schema present, the description covers the essential function and expected data. It even enumerates the track fields, which is more than necessary given the output schema. The tool is simple, and the description is complete enough for an agent to invoke it correctly.

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

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

The input schema only defines project_id as a required number with no description coverage. The description adds meaning by explaining that project_id identifies a LibriVox recording project, but it does not elaborate on how to find the ID or what constitutes a valid value. Given the low schema coverage, the description compensates only minimally.

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

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

The description clearly states the tool retrieves individual chapter tracks for a given LibriVox project, identified by project_id. It distinguishes from sibling tools like 'audiobook' and 'audiobooks' by focusing on tracks rather than the overall record. However, it uses 'answers' rather than a more direct verb like 'retrieves' or 'lists', making the action slightly less immediate.

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

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

The description implies the tool is used when you have a project_id and need track-level details, but it does not explicitly state when to prefer this tool over alternatives such as 'audiobook' or 'audiobooks'. No exclusions or prerequisites are mentioned, so guidance is only contextual rather than direct.

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

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

The description goes beyond the annotations by clarifying that the row is deactivated, not deleted, which explains the destructiveHint=false annotation and prevents a dangerous misunderstanding. It also discloses ownership enforcement and the preservation of historical events, offering valuable behavioral context not present in the structured 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?

The description is two sentences, front-loaded with the core action, and every clause adds important detail. It is concise, structured effectively, and free of 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?

For a simple mutation tool with a single parameter and no output schema, the description covers the essential aspects: the action, the target, ownership constraints, the side effect (deactivation), and the relationship to recent_alerts. No critical information is missing for an agent to use it correctly.

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

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

The input schema already provides a clear description for the 'id' parameter, but the description adds meaningful context by stating that ownership is enforced, implying the id must be a subscription owned by the caller. This clarifies how to use the parameter beyond its schema definition and compensates for the minimal schema detail.

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

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

The description clearly states the verb ('Cancel') and resource ('a subscription by id'), making the tool's function immediately obvious. It also differentiates from sibling tools like subscribe and list_subscriptions by specifying cancellation semantics.

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 mentions ownership enforcement, a key prerequisite, and points to recent_alerts for accessing historical events, providing useful context. However, it does not explicitly name alternatives or exclusion criteria (e.g., 'use subscribe to create'), so it stops short of a fully explicit when/when-not guide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds rich behavioral nuance: it lists possible verdicts, explains that 'could_not_verify' means verification did not happen and must not be treated as evidence, distinguishes it from 'unsupported', and notes the verification_error field. This goes well beyond the annotation baseline.

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

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

The description is long but deliberately structured: it opens with query phrasings, then explains routing, return values, and a critical caller warning. Every sentence earns its place, and the 'IMPORTANT for callers' section isolates the most critical caveat. 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 carries the full burden of conveying return semantics—and it does so thoroughly. It enumerates all six verdicts, explains the distinction between 'could_not_verify' and 'unsupported', describes the citation format, and notes the two internal pipelines. The description is complete enough for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, and both parameters (claim and tolerance_pct) are already well documented in the input schema with examples and semantics. The main description adds marginal context by mentioning 'exact percent-delta math' but does not materially extend the parameter understanding 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's function: natural-language claim verification against authoritative sources, with explicit query phrasings and an unambiguous verb ('verify'). It distinguishes itself from siblings by detailing the structured SEC EDGAR/XBRL fast path for company-financial claims versus the grounded pipeline for all other claims, making its scope precise.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and further guides on the two routing paths (financial vs. other claims). It even notes that the tool replaces 4–6 sequential calls, which frames when to prefer it over a multi-step alternative. No exclusions are stated, but the context is clear.

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