Stooq

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

Annotations already declare read-only, idempotent, non-destructive. The description adds significant context beyond annotations: the free default model, the BYO Anthropic key with direct cost to the caller, and the detailed per-model return structure. 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 three sentences, front-loaded with the core function, followed by model details and use cases. Every sentence earns its place, with no fluff or repetition. Ideal structure for quick agent parsing.

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 4 documented parameters and no output schema, the description compensates by specifying the return structure and concrete use cases. It gives enough information for an agent to decide when to invoke it and what results to expect. Coverage is comprehensive relative to complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the default model and _apiKey requirement for Anthropic, but the schema already explains these details thoroughly. The description adds little beyond what the schema provides, though it does clarify the 'combined view' and scoring range.

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 probes one or more LLMs for what they know about a business/brand/product/topic and scores visibility 0-100 per model. It names the specific action ('probe', 'score') and the resource (LLMs), and the per-model output structure distinguishes it from siblings like ask_pipeworx or scan_competitor_ai_presence.

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

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

The description explicitly names use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also mentions the default model and when to pass _apiKey to include Anthropic. However, it lacks an explicit contrast with alternative tools, so the agent must infer when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds meaningful behavioral context beyond this: it routes to 5,529 tools across 1,455 sources, returns citation URIs, works on every tier, and is a single fast call. No contradiction with annotations, and the extra operational details are valuable.

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

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

The description is long but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and every sentence serves a purpose: use cases, examples, escalation paths, and coverage scope. It is structured in a way that facilitates quick scanning, though it could be trimmed slightly without losing value.

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

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

For a tool with no output schema and high complexity, the description adequately explains what the tool returns (structured answer with citation URIs) and covers operational context like tier compatibility and speed. It also provides diverse examples that clarify scope. It does not specify exact output formatting or error behavior, but it is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% with the 'question' parameter fully described and aliases listed. The description does not add parameter-specific semantics beyond the schema, but it does provide illustrative examples that suggest acceptable query formats. Since the schema already covers the parameter, a baseline score of 3 is appropriate.

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

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

The description clearly states this tool routes questions to one of 5,529 tools across 1,455 sources and returns a structured answer with stable pipeworx:// citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and the verb 'routes' plus the resource 'questions about current or historical data' makes the purpose unambiguous.

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

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

The description gives explicit when-to-use guidance ('Use whenever the user asks...', 'START HERE for most questions') and explicitly names alternatives for step-up scenarios ('use ask_pipeworx_grounded' for hallucination-resistant answers, 'deep_research' for broad/multi-part questions). It also advises preferring this over web search, which is clear comparative usage guidance.

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

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

With annotations already indicating read-only, open-world, idempotent, and non-destructive behavior, the description adds valuable context about its experimental nature: candidate routing improvements are enabled live, results are compared to the stable router, and it falls back to nothing—meaning it is fully functional. This goes beyond the annotations without contradicting them.

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

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

The description is slightly verbose but every sentence earns its place: it covers the beta purpose, current state, usage instructions, and fallback behavior. The structure front-loads the core definition and then provides context, which aids readability while remaining reasonably concise.

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

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

For a universal router with no output schema, the description effectively leverages the sibling ask_pipeworx to convey the response shape and behavior. It also covers the experimental aspect and fallback behavior, making it sufficiently complete for an agent to use the tool correctly, though a brief example or return format could push it higher.

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

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

Schema description coverage is 100% with all aliases documented. The description adds no additional parameter semantics beyond stating 'same arguments' as ask_pipeworx, which is redundant with the schema. Baseline 3 is appropriate since the schema already carries the burden.

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

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

The description clearly states it is the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape, while explicitly differentiating it as the experimental edge with candidate routing improvements. This distinguishes it from siblings like ask_pipeworx and ask_pipeworx_grounded.

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

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

The description provides explicit guidance on when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no active candidate, matches stable exactly). However, it does not explicitly state when not to use it (e.g., for production stability), so it falls short of a 5.

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

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

Describes grounded extraction, evidence verbatim quote, confidence, refusal reasons, and extra LLM call cost, complementing readOnly/idempotent hints. This gives the agent a clear model of runtime behavior and failure modes beyond annotations.

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

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

Five dense sentences, each communicating distinct critical info: purpose, routing mechanism, return format, use cases, and cost tradeoff. Front-loaded with the primary purpose and no wasted words.

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

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

With no output schema, the description provides full return and refusal structures, success/error examples, and use-case guidance. It covers what the agent needs to know to invoke and interpret the tool correctly without any major gaps.

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

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

Schema has 100% coverage with all aliases documented; description doesn't add specific parameter syntax or constraints beyond use-case context. Baseline 3 is appropriate because the schema already handles 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 clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, and distinguishes it from ask_pipeworx by emphasizing extraction using only tool results and explicit refusal behavior. This is more than a tautology; it conveys a distinct tool purpose and scope.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on...'), lists example domains (financial, legal, medical), and contrasts with ask_pipeworx ('prefer ask_pipeworx for casual lookups') including the cost tradeoff. This is exemplary guidance for choosing among 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 this read-only, open-world, idempotent, non-destructive. The description goes far beyond by detailing resolver contracts (market_match_confidence, alternatives), parent_event extractor, news fallback behavior, low-confidence short-circuiting, closed-market handling, and cancellation-rule risk. This adds significant behavioral 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 long but highly structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every section adds critical operational detail for an agent, though some redundancy exists (e.g., repeated 'blocking' note). It is appropriately sized for the tool's complexity, but not as concise as the calibration high example.

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 return shapes: result.market, result.analysis, result.evidence, result.market_match_confidence, parent_event, news fallback fields, status codes, and tradeability flags. It also includes safety warnings and cancellation-rule risks, making it complete for a complex research tool.

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

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

Input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds example formats for the 'market' parameter and explains the impact of 'depth' and 'include_raw' indirectly through fan-out and response size notes, but it does not materially enhance the parameter semantics beyond the schema.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools (e.g., polymarket_arbitrage, polymarket_edges) by focusing on bet research with data fan-out, and it provides concrete input formats and output components.

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

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

Explicit usage guidance is given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides detailed fan-out examples for different bet categories and explains blocking paths (low_confidence_match, market_closed_or_inactive), making it clear when the tool should and shouldn't be trusted.

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 strong annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavioral context: it names data sources (SEC EDGAR/XBRL, FAERS), explains fiscal-year handling for off-calendar companies, reveals sorting by primary metric, and notes citation URIs. This goes well beyond the annotations.

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

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

The description is dense and structured, starting with trigger phrases and then providing details per type. While longer than some, every sentence adds value, and the layout is logical. Minor deduction for being somewhat packed, but it remains appropriate 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?

Even without an output schema, the description explains return format ('paired data + pipeworx:// citation URIs'), data sources, scope limits (2-5 entities), and efficiency benefits. It fully covers what the agent needs to know for correct invocation and result interpretation.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches both parameters: it explains the 'type' enum options and clarifies that 'values' are arrays of tickers/CIKs for companies and drug names for drugs, with examples. This adds practical meaning beyond the raw 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: side-by-side comparison of 2-5 companies or drugs in a single parallel call. It specifies what data is pulled (10-K financials, FAERS counts, trial counts) and distinguishes itself from sequential lookups, making it unmistakable versus siblings like entity_profile.

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

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

Explicit guidance is provided: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives concrete example phrasings and explains when to use each type ('company' vs 'drug'), making the tool's intended context very 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 the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description discloses account/tier requirements, latency (15-60s, up to ~90s), the 'never invented' accuracy guarantee, gaps[] for unanswered facets, contradictions[] for disagreements, and that citation_uri is always resolvable. These are substantial behavioral traits not captured in the annotations.

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

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

The description is long but information-dense, front-loading the essential account requirement and then explaining purpose, alternatives, depth behavior, citation format, and latency. However, some redundancy with the schema's depth explanation ('depth:"standard" re-angles unanswered gaps') makes it slightly less concise than it could be.

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

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

For a complex tool with no output schema, the description thoroughly covers the input, execution model (parallel facet decomposition), output structure (verbatim evidence + confidence + source + fetched_at + citation_uri + gaps[] + contradictions[]), limitations (empty gaps for non-catalog news topics), and performance. It even explains excerpting behavior for large records, making it 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?

The input schema already provides 100% coverage of both parameters with rich descriptions of the depth enum (quick/standard/thorough) including facet counts and hop behavior. The description adds context about depth's impact on multi-step resolution and the paid plan, but largely restates existing schema details, so it remains at the baseline.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' by decomposing questions and routing facets to tools in parallel. It explicitly distinguishes itself from open-web search and from ask_pipeworx (single lookup), making its unique 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?

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and names alternatives for other scenarios: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and if not signed in, use ask_pipeworx instead. This is exceptionally clear direction.

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 safety profile is covered. The description adds behavioral detail: it returns top-N tools with names, descriptions, and full input schemas (with curated examples), and each result is ready to call directly without a second lookup. This informs the agent about the response format and efficiency, beyond what annotations convey.

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

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

The description is four sentences and front-loads the purpose with 'Find tools by describing the data or task.' The domain list is long but relevant and useful for the agent to understand the tool's scope. No wasted words, though it could be slightly tighter.

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 explains the return format (top-N tools with schemas and examples) and the 'ready to call directly' behavior. For a discovery meta-tool with a simple parameter set, this is reasonably complete. Edge cases like empty results aren't mentioned, but that's not critical for this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic context by enumerating the domains the tool can discover (SEC filings, FDA drugs, FRED, Census, etc.) and clarifies that the query is a natural-language description of data or task. This helps the agent craft better queries.

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

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

The description clearly states the tool's function with a specific verb ('Find tools') and resource ('by describing the data or task'), and lists concrete domains. It distinguishes itself from sibling tools by being a meta-tool that returns ready-to-call schemas, and explicitly positions itself as the 'FIRST' discovery step.

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

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

It gives explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clarifies when to use it rather than directly invoking a specific sibling tool. It doesn't name alternatives, but the 'not just one answer' implies the exclusion of direct tool calls.

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 details beyond the annotations: it fans out across multiple source systems, returns specific fields (CIK, filings, fundamentals, patents, news, LEI), and includes soft-fail behavior for the PatentsView API sunset and GDELT→GNews fallback. This is exactly the kind of context that helps an agent set expectations and interpret results. No contradiction with the readOnly/openWorld/idempotent annotations.

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

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

The description is a single dense paragraph, but every clause carries information: examples, when-to-use, data sources, return fields, caveats, and input constraints. It could be more structured (e.g., bullet points), but it avoids waste and front-loads with examples and the key 'ALWAYS PREFER' directive. For a tool with this complexity, the length is justified.

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

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

Given no output schema, the description compensates by enumerating all major return components: recent_filings with URIs, fundamentals, patents, news, and LEI. It also covers source systems and fallback behavior. This is complete for an agent to invoke the tool and interpret the result, especially with the explicit 'names not supported' caveat.

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 'type' and 'value' parameters are described in detail, including the ticker/CIK format and the fact that names are unsupported. The description reinforces this but does not add meaning beyond the schema. The example values ('AAPL', '0000320193') are helpful but already present in the schema, so the description adds no new 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 clearly states a specific verb ('profile') and resource ('US public company'), with a precise scope: 'full cross-source profile in ONE parallel call.' It includes concrete example queries and explicitly distinguishes itself from sibling tools like compare_entities and resolve_entity by focusing on holistic company research.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names the fallback for name-only inputs: 'use resolve_entity first if you only have a name.' This clear direction helps the agent select the right tool and avoid unnecessary chaining.

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, covering the key behavioral traits. The description adds context about the memory being 'previously stored' and the use case for clearing sensitive data, but does not disclose additional behavior such as error handling or irreversibility. With annotations present, this is adequate but not exceptional.

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

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

The description is two concise sentences, front-loaded with the primary action and followed by usage context and sibling references. Every sentence earns its place with no redundancy or filler.

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

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

For a simple tool with one parameter, no output schema, and annotations covering safety and idempotency, the description fully captures purpose, usage, and related tools. The agent has sufficient information to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents the 'key' parameter as 'Memory key to delete'. The description only mentions 'by key' and 'previously stored memory', which does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and resource. It distinguishes itself from sibling tools like 'remember' and 'recall' by explicitly labeling this as deletion, making its unique purpose unambiguous.

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

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

The description provides explicit guidance on when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier') and mentions pairing with 'remember and recall', giving clear context and alternatives without needing further inference.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to cover safety. It adds valuable context by disclosing the internal process: fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. This goes beyond annotations and helps the agent anticipate behavior, though it omits potential issues like rate limits or network errors.

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 plus a 'Useful for' list, with the main action front-loaded. Every sentence contributes: the first states the purpose and output, the second details the process, and the list provides use cases. No waste 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 relatively simple tool with full schema coverage and strong annotations, the description covers purpose, process, output format, and use cases. It doesn't describe error handling or edge cases, but given the tool's simplicity and the annotations, this is sufficient. The lack of an output schema is mitigated by the explicit description of the text blob output.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (url and max_links). The description adds minimal extra meaning, such as implying that 'key links' relate to the max_links parameter, but it doesn't elaborate on defaults or constraints. This aligns with the baseline score of 3 for high schema coverage.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb ('generate'), resource ('llms.txt file'), and scope ('any URL'). It also explains the process (fetches, extracts, emits) and differentiates from sibling tools by focusing on llms.txt generation, a unique capability not evident in other tool names.

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 concrete use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'), which gives clear guidance on when to use it. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5.

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

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

Given the annotations (readOnlyHint=true, destructiveHint=false), the description adds valuable context beyond the safety profile: it specifies that results are scoped to the caller ('the caller's active subscriptions') and lists the exact return fields. This discloses behavioral traits (data scope and output shape) not captured by annotations.

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

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

Two sentences: the first states the purpose, the second provides actionable usage guidance. Every word earns its place, and the most critical information is front-loaded. No redundancy or unnecessary detail.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description is complete: it covers purpose, return fields, and use cases. The annotations cover safety, and the schema covers parameters. No significant gaps remain.

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

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

The schema fully describes the only parameter (include_inactive with a clear description and default). The description's mention of 'active subscriptions' implicitly reinforces the default behavior but doesn't add significant new meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and enumerates the returned fields (id, type, params, etc.). It is easily distinguished from sibling tools like subscribe/unsubscribe, and the first sentence immediately establishes its core function.

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

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

The description provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly ties to sibling tools (subscribe/unsubscribe) and gives concrete when-to-use context. It doesn't explicitly state when not to use it or name alternatives, but the guidance is strong enough for an agent to select it 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?

Annotations provide basic safety hints (readOnlyHint=false, destructiveHint=false), but the description adds valuable behavioral context: it discloses rate limits ('Rate-limited to 5 per identifier per day'), that it's free and doesn't count against tool-call quota, and that filing without an account returns a claim_token for later follow-up. It even explains the team reads digests daily and feedback affects the roadmap. 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 longer than average, but every sentence carries weight. It is front-loaded with the core purpose, then moves logically through usage, exclusions, mechanics, and constraints. There is no filler or repetition; each clause adds new information.

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

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

Given that the tool has no output schema, the description fully compensates by explaining what to expect: claim_token, later status check, and what changes when resolved. It also covers prerequisites (account vs. no account), rate limits, and scope boundaries. This is complete enough for an agent to invoke and follow up properly.

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 input schema already documents all parameters (100% coverage), the description enriches them by illustrating the claim_token workflow: 'Filing without an account returns a claim_token; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed.' It also clarifies the 'type' parameter by naming the categories (bug, feature, data_gap, praise) in context, and advises on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt').

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 purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly distinguishes itself from siblings by restricting scope to 'ONLY for tools served by this Pipeworx connection,' and clarifies that feedback for other servers should go elsewhere. This makes the tool's role unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also tells users when not to use it, stating that feedback about other MCP servers should be filed with that server instead. This is strong, actionable 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 read-only, open-world, and idempotent behavior, but the description adds valuable context beyond that: it reveals the data source ('derived from CF analytics-engine'), privacy ('no PII'), and caching behavior ('Cached 5min-1h depending on window'). This gives agents a fuller understanding of what to expect.

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

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

The description is three sentences long and front-loaded with the core purpose ('What other AI agents are calling on Pipeworx right now'). Each sentence earns its place: purpose, use cases, and technical transparency. No fluff or repetition.

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

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

With no output schema, the description sufficiently covers return content by mentioning 'top tools, top packs, total call volume' and specifying the tuple '(pack, tool, count)'. It also addresses data source and caching, making the tool's behavior complete for an agent without needing additional inference.

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

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

The schema already fully describes the 'window' parameter with an enum and explanation of trade-offs, providing 100% coverage. The description adds a little extra by indicating that caching varies by window (5min-1h), which is not in the schema, so it earns a score above the baseline of 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 clearly states the tool's function with a specific verb and resource: 'Returns the top tools, top packs, and total call volume' over a recent window. It distinguishes itself from siblings by focusing on aggregating other AI agents' call activity, which is unique among the listed 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 provides three concrete use cases: discovering hot data sources, confirming canonical tools before asking, and aligning with agent needs. This gives clear context for when to use the tool, but does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare read-only/idempotent behavior, but the description adds substantial context: partition filtering logic, semantic anchor similarity threshold, fill check against live CLOB depth, and the warning not to trade when realizable_edge_pp ≤ 0. These disclose limitations and edge cases comprehensively.

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 appropriately structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK) and front-loaded with the main purpose and mode selection. Every section adds necessary detail for correct tool invocation, with no redundancies.

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

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

Given the tool's complexity (multiple modes, filtering, response format) and the absence of an output schema, the description is remarkably complete. It explains the response structure, the fill check pricing mechanism, and even references related tools, covering all essential aspects for correct use.

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 descriptions cover both parameters, but the tool description enriches them with concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal') and clarifies the default no-arg behavior. It explains the semantic difference between event and topic modes, which the schema alone does not convey.

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

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

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

Explicit usage guidance is provided: '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 recommends event for specific markets and topic for cross-event scanning, and even directs custom sizing to polymarket_fill_risk as an alternative.

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

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

Goes well beyond annotations by disclosing response structure (by_segment, fed_candidates, _diagnostics), caching ('Cached 1h at the KV level'), edge calculation nuances, placeholder filters, and a market-move warning. No contradiction with 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 extremely dense and includes historical details (e.g., 'gates relaxed Run 8 from prior 85%/5%/50:1') and extended reasoning about Fed data that may be unnecessary for an agent. While structured into sections, it is verbose and could be tightened.

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 provides a thorough top-level response structure, segment definitions, field names, filter behaviors, diagnostics for empty segments, and edge cases like placeholder filters and Fed candidates. It is remarkably complete for the tool's complexity.

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

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

Schema covers 100% but the description adds meaningful rationale: slippage context (zero fees but 20-50bp impact), why min_partition_leg_kelly exists (parent kelly_fraction_half is always 0 for partition arbs), and framing knobs as 'tradeable-edge' filters.

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 action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states the verb, resource, and scope, and distinguishes it from siblings by focusing on Pipeworx disagreement and unique model segments.

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 positioned as 'what should I bet on today' and explains when to use tradeable-edge knobs like min_liquidity/max_spread_pp. It does not directly contrast with sibling tools but provides sufficient context for appropriate 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 readOnly/idempotent/non-destructive, so the description adds significant behavioral context beyond that: it explains the 60-day snapshot TTL, gaps in snapshots due to cache-miss behavior, decay computed from daily closes (not intraday), and the distinction between expired and tracked opportunities. 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?

Although lengthy, the description is well-structured with explicit sections (Args, RESPONSE, LIMITS) and every sentence conveys essential information. It is front-loaded with the core purpose, then details response fields and limitations. 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?

Given the tool's complexity (time-series, trends, expiry) and lack of an output schema, the description fully compensates by detailing the response structure (tracked[], expired[], snapshot_dates[]) and their semantics. It also covers data freshness and calculation caveats, making it complete for an agent to understand what it will receive and how to interpret it.

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

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

Schema coverage is 100% and both parameters are clearly described with defaults and ranges. The description restates the parameters but adds minimal extra meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('tracks persistence and decay') and resource ('edge_pp_net time-series from polymarket_edges snapshots'). It answers the exact question 'how long has this edge existed and is it shrinking?', which distinguishes it from sibling tools like polymarket_edges that likely provide current edge data.

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

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

The description implies when to use this tool by framing the analytical question ('a fresh wide edge and a 3-week-old wide edge are different trades'). It also hints at a use case ('your competition clock') but does not explicitly name alternative tools or state when not to use it. Clear context, but missing explicit exclusions.

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

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

Annotations already declare read-only, idempotent, and non-destructive, and the description reinforces this by describing a read-only computation via live order-book depth. It adds detailed behavioral context: walks the ladder, returns top_of_book/vwap/slippage/verdict, and spells out the risk that partial basket fills convert an arb into an unhedged directional position. No contradiction with annotations.

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

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

Front-loaded with the core purpose, then uses 'SINGLE-MARKET:' and 'BASKET:' labels to segment. It is long and dense, but the information is highly specific and relevant; it could be broken into bullets but earns its length given two modes and no output schema.

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

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

Since there is no output schema, the description lists the full set of return values for both modes (e.g., vwap_fill_price, capture_ratio, thin_legs[], forced_directional_risk) and explains their semantics. It also covers input requirements, defaults, clamp range, and the primary use case/risk. Extremely complete for the tool's complexity.

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

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

Schema covers all four params, but description enriches semantics: defines side defaults per mode, interprets size_usd differently for single (max spend/target proceeds) vs basket (settlement notional S, shares per leg), and clarifies market/event mode selection. This goes well beyond the schema's property 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 opening phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth' clearly identifies the tool's function. It distinguishes from sibling analysis tools by scoping to fill/execution risk and explicitly positions itself before 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?

States an explicit trigger: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also separates single-market vs basket mode and warns against partial fills, giving clear usage context. No direct 'when not to use' beyond the implied threshold and thin-book warning, but the guidance is strong.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, but the description goes far beyond that. It discloses the exact conditions for compatibility_warning, the meaning of temporal_alignment (aligned:false makes spreads meaningless), and the skipped_cross_type/subtype counters that expose dropped comparisons. This is rich behavioral context with no contradictions to 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 exceptionally well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, covering purpose, usage, response, safety warnings, and practical caveats without redundancy. Front-loaded with the core purpose, it is appropriately sized for a tool with this level of nuance.

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 describing the response structure (leg-by-leg prices, spread.top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It also addresses edge cases (non-equivalent bet shapes, unrelated events) and provides a realistic caveat about tradeability. For a complex cross-venue spread tool with 3 optional params, 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 descriptions for all three parameters, giving a baseline of 3. The description adds meaningful semantics by explaining the two modes and override behavior (explicit ticker/slug overrides topic-mapped side), plus providing concrete examples like 'fed' and 'KXFED-26OCT'. This goes beyond the bare schema.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from sibling tools (e.g., polymarket_arbitrage) by focusing on the cross-venue comparison and explicitly detailing two operational modes (topic shortcuts vs explicit ticker/slug).

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

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

The description explains both usage modes and warns that pre-mapped topics often return compatibility_warning and are not necessarily tradeable ('pre-mapped ≠ tradeable'). It provides clear context for when the delta is meaningful (equivalent bet shapes) and when the tool reports non-equivalence. However, it does not explicitly name alternative tools or state when not to use this tool versus other Polymarket 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 cover readOnlyHint, idempotentHint, and destructiveHint, lowering the bar. The description adds valuable non-annotation context: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID). It also clarifies the dual-mode behavior (retrieve by key vs. list all keys), which goes beyond 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 exactly three sentences with no fluff. The first sentence states the core function, the second covers the use case, and the third addresses scoping and pairing with sibling tools. It is front-loaded and every sentence earns its place.

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

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

For a simple read-only memory tool with one optional parameter, the description is nearly complete. It covers both modes, the intended use case, and scoping to the agent's identifier. Minor gaps like behavior for missing keys or exact return format are not critical given the tool's simplicity and the absence of an output schema.

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

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

The schema already provides 100% coverage for the single 'key' parameter, including the omit-to-list behavior. The description enriches semantics by giving typical key examples (user's target ticker, address, prior research notes) and reinforcing the omit behavior. This exceeds the baseline expected with full schema coverage.

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

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

The description uses specific verbs 'Retrieve' and 'list' with a clear resource ('a value previously saved via remember'). It distinguishes the tool from sibling tools 'remember' and 'forget' by explicitly describing the retrieval and listing behaviors. Concrete examples (ticker, address, research notes) further reinforce the purpose.

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

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

The description clearly states when to use the tool: 'to look up context the agent stored earlier without re-deriving it from scratch.' It also references companion tools 'remember' and 'forget' to frame the full lifecycle. However, it does not provide explicit when-not-to-use guidance or name alternative lookup tools, so it lacks strong 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 declare readOnlyHint:true, but the description explicitly describes a state mutation: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This contradicts the read-only hint, making the behavioral disclosure unreliable.

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 remarkably concise: two sentences of core behavior and one sentence about polling/endpoint. Every clause adds value, no fluff or repetition.

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

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

With no output schema, the description compensates by disclosing return fields and important behaviors (filtering, mark_read, polling). It doesn't mention limit or unread_only, but those are adequately described in the schema. The mark_read contradiction and lack of interaction semantics (e.g., unread_only + mark_read) leave some gaps.

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

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

Although the input schema already covers all 5 parameters (100% coverage), the description adds useful meaning by giving an example type ('sec_8k'), explaining the mark_read side effect, and describing what each returned event contains. This goes beyond the schema's descriptions.

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

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

The description opens with a clear verb+resource ('Pull fired events from your subscription feed') and specifies return fields (source, citation_uri, raw event payload). It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on 'fired events' from the 'persisted feed'.

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

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

The description gives practical guidance: 'Polls work fine' signals suitability for repeated polling, and it mentions an alternative HTTP endpoint for scripts/dashboards. It lacks explicit exclusions or comparisons with sibling tools, 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.

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

Annotations already declare readOnly/idempotent/non-destructive, and description adds substantial behavioral context: parallel fan-out to multiple sources, fallback on rate limits/5xx, USPTO soft-failure due to API sunset, `since` shorthand, and return structure. 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?

Dense but well-structured: front-loads query intent, then details sources, parameter formats, output, and alternative tool. Every sentence adds value and no filler is present.

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

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

Despite no output schema, description states return shape (changes[] grouped by source, total_changes, citation URIs). Given multi-source complexity and fallback behavior, the description is fully self-contained for an agent to decide and invoke correctly.

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

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

Schema covers all three parameters with descriptions, so baseline is 3. Description enriches this by explaining `since` relative shorthand forms and giving value examples (ticker/CIK), adding meaningful semantics beyond schema without redundancy.

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

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

Description clearly states a specific function: returning a change feed for a company over a time window, with concrete query examples. It also distinguishes itself from sibling tool entity_profile by explicitly naming the alternative for static profile needs.

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 cues via natural language examples and explains data source behavior (SEC, GDELT/GNews fallback, USPTO). It also gives an explicit alternative: 'Use entity_profile instead when you want the static profile...' which is strong 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 provide idempotentHint=true and destructiveHint=false, but the description adds valuable non-obvious behavior: memory is scoped by identifier, authenticated users get persistent storage while anonymous sessions retain for 24 hours. This goes beyond annotation data and sets accurate expectations for retention and scope.

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 with front-loaded purpose, then usage guidance, then storage details and related tools. Every sentence earns its place; no redundancy or fluff.

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

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

For a simple two-param write operation with no output schema, the description covers what the tool does, when to use it, persistence behavior, and related counterparts. It is complete and leaves no significant gaps for an agent to misuse the tool.

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

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

Schema description coverage is 100% with rich descriptions for both key and value, including format examples. The description adds that it is stored as a key-value pair scoped by identifier, which is more about behavior than parameter semantics. Baseline 3 is appropriate given the schema already carries the load.

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 verb 'Save data' and clearly identifies the resource: data needed for later reuse across conversations/sessions. It distinguishes from siblings like recall and forget by explicitly pairing with them, making the tool's role in the memory workflow unambiguous.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward' with concrete examples (ticker, address, preference). It also names alternatives for related operations: 'Pair with recall to retrieve later, forget to delete,' providing clear guidance on tool selection within the sibling set.

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

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

Beyond the read-only annotations, the description discloses significant behavioral traits: it cascades through multiple lookup endpoints, degrades gracefully if GLEIF/OpenFIGI are unavailable, labels identifiers with their source, and explicitly lists unresolved identifiers. This adds substantial context not captured by annotations or 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 long and dense, but it is front-loaded with trigger examples and organizes information by type. Each sentence contributes useful details, though the company 'parenthetical' is a run-on that could be better structured. Overall, the length is justified by the tool's complexity and lack of an output schema.

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

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

Even without an output schema, the description thoroughly explains return values for both supported types, including source labeling and unresolved identifiers. It also covers graceful degradation and the fact that it replaces manual lookups. Given the tool's moderate complexity, the description is complete and leaves no major gaps.

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

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

The input schema already covers both parameters with descriptions and an enum for type (100% coverage). The description reiterates accepted inputs for 'value' but does not add new parameter-level semantics beyond what the schema provides. It focuses on output details rather than parameter nuances.

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: resolve user-spoken names to canonical/official identifiers. It uses specific verbs like 'resolve' and 'look up', and explicitly says 'Use FIRST whenever you have a name but need an ID.' This distinguishes it from sibling tools like compare_entities or entity_profile, and the supported types are enumerated.

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

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

The description gives strong usage guidance with 'Use FIRST whenever you have a name but need an ID' and provides concrete example queries that trigger the tool. It does not explicitly mention alternatives or when not to use it, but the directive is clear enough to guide selection.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses internal behavior: it calls ai_visibility_check per entity, ranks results, and returns a ranked list with score, confidence, and signal density. This adds useful operational detail 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?

Two sentences efficiently cover the tool's function, mechanism, use case, and output format without redundant phrasing. The description is front-loaded with the core comparative action and remains easy to parse.

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 fully explains the tool's purpose, internal method, when to use it, and what it returns (ranked list with score, confidence, signal density). Since there is no output schema, this return-format information is critical and provided, making the tool understandable for a complex comparison task.

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 does not add parameter-specific detail beyond what the schema already documents; it only references entities and the probing mechanism. No additional parameter meaning is introduced.

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

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

The description states a specific verb ('Compare'), a resource ('AI visibility across multiple entities'), and a method ('probes each entity with ai_visibility_check, ranks by score'). It explicitly contrasts with single-entity tools by emphasizing side-by-side comparison, making it clearly distinct from sibling tools like ai_visibility_check.

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 concrete use case ('competitive AI-marketing audits') and an illustrative question, showing when the tool is applicable. However, it does not explicitly name alternative tools or exclusion criteria (e.g., when to use ai_visibility_check instead), so guidance is clear but lacks explicit alternatives.

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

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

The description adds significant behavioral context beyond the annotations: it describes fan-out architecture, graceful degradation, potential 5-30s delay on first bundlephobia measurement, and the sources_failed field. This is exactly the kind of runtime behavior an agent needs to set expectations.

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

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

Four sentences, each earning its place: purpose, use cases, return data, limitations. The structure front-loads the primary purpose and then efficiently covers exceptions and fallback behavior without wordiness.

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

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

No output schema exists, so the description must enumerate return values, which it does comprehensively (summary fields, per-advisory details, links, recent alternatives). It also covers ecosystem scope, timing, and partial-failure behavior, making the tool fully self-contained for an agent.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description does not add any parameter-specific semantics; it only reiterates that the package is an npm name and version defaults to latest. The baseline 3 applies as the schema carries the burden.

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 verb and resource: a composite "should I add this npm package" check. It specifies the two data sources (deps.dev and bundlephobia) and distinguishes from siblings by noting NPM-only support in v1, making its scope unambiguous.

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

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

Explicit triggers are given: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." It also provides an exclusion: non-NPM ecosystems fall under deps.dev:version directly, clarifying when NOT to use this tool. This is strong guidance for an agent.

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, the description reveals implementation details: BGE-base-en embeddings, cosine over 500-char windows, a 200K character cap with truncation flagging, and the guarantee of character offsets for verbatim verification. This adds substantial context not available from annotations alone.

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

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

The description is front-loaded with purpose and usage, then moves to pairing and technical details. Every sentence contributes, though the embedding and window-size details are somewhat dense for a tool selection context. Still, it is well-structured and not wasteful.

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

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

With no output schema, the description explains return values: 'top-N passages with character offsets and similarity scores.' It also covers edge cases (truncation flagged), input constraints (200K cap), and the intended workflow with ask_pipeworx_grounded, making it highly 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 enhances parameters by framing 'text' as 'already pulled' content, providing examples for 'query', and noting the character cap. This adds useful context beyond bare schema descriptions.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' specifying a clear verb and resource. It distinguishes from sibling tools like ask_pipeworx_grounded by explicitly stating it pairs with that tool, and the focus on returning passages with offsets sets it apart.

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

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

Explicit guidance is provided: 'Use when the record is too big to cram into the prompt.' It also describes a complementary workflow with ask_pipeworx_grounded, giving a clear when-to-use and alternative.

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

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

Annotations indicate a mutating, idempotent operation. The description adds valuable context beyond annotations: it returns a subscription id, requires OAuth persistence, describes the always-on feed, and discloses SMS limits and phone verification. It does not contradict annotations and offers meaningful operational details.

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

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

The description is dense but well-organized: purpose, return value, auth requirement, type examples, and delivery options in a logical order. Every sentence carries necessary information, though it is a long paragraph; no fluff, but could benefit from bullet points for readability.

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

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

The tool has no output schema, so the description must convey the response (subscription id) and prerequisites. It covers purpose, auth, type-specific examples, delivery channels, and limits. The detailed input schema fills in the rest. The only minor gap is no explicit description of the subscription object itself, but the id is likely sufficient for a creation tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds semantic value beyond the schema by clarifying example types (e.g., sec_8k items:["5.02"] = officer change) and delivery channel behavior (SMS cap, webhook details). This enriches understanding beyond the structured parameter definitions.

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

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

The description begins with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states the returned value (subscription id) and lists supported types, distinguishing it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description specifies when to use (proactive monitoring) and provides an explicit alternative for the feed channel: 'pull via recent_alerts or GET registry.pipeworx.io/alerts.json.' It also states requirements and restrictions, such as needing an OAuth account (anonymous + BYO cannot persist) and SMS verification with a 10/day cap, effectively guiding when not 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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it returns 'category-bucketed example questions' with 'exact tool + argument shape', and notes it draws from the 'live catalog of thousands of tools' — a dynamic behavior not captured by static 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 moderately long but well-structured: it front-loads example queries and defines the tool's role in the first two sentences, then efficiently covers return format and invocation. Every sentence contributes useful information, though it could be tightened slightly.

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

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

For a tool with a single optional parameter and no output schema, the description fully covers what it returns (category-bucketed questions with tool calls), how to call it (with or without `topic`), and when to use it (first-time onboarding). Context is complete with no gaps.

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

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

The input schema already enumerates all `topic` values and explains the omission behavior. The description's examples ('finance', 'pharma', 'betting') are subsets of the schema list, adding no new meaning. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description opens with concrete example queries and explicitly states the tool is 'the onboarding entry point for an agent that just connected' — a clear verb+resource statement. It distinguishes itself from siblings by emphasizing its role in learning what Pipeworx can do, rather than executing specific research tasks.

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

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

Provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also references alternatives like ask_pipeworx and entity_profile, making the intended context unmistakable.

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

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

The description adds behavioral details beyond the annotations: ownership enforcement, deactivation rather than deletion, and historical events remaining available. These context-rich specifics align with and complement the annotations (idempotentHint, destructiveHint), 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 consists of three sentences, each earning its place: the action, the ownership constraint, and the side-effect on historical events. It is front-loaded with the main verb and contains 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?

For a simple single-parameter tool with no output schema, the description covers the core behavior and side effects comprehensively. It could add error-handling details (e.g., behavior for invalid or foreign ids), but the essential functionality is clearly communicated.

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 'id' parameter, and the description adds meaning by stating that the id must be the caller's own subscription, which is not in the schema. This enriches the parameter semantics beyond the basic type and source.

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

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

The description clearly states the action ('Cancel a subscription by id') and specific resource, distinguishing it from siblings like subscribe or recent_alerts. The additional details about ownership and deactivation further clarify the tool's purpose.

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

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

The description implies usage for canceling subscriptions and notes that ownership is enforced, but it does not explicitly state when to use this tool versus alternatives or when not to use it. The deactivation behavior provides some context, but no explicit exclusions are given.

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

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

The description adds critical behavioral context beyond the annotations (readOnly, openWorld, idempotent, non-destructive). It explains the dual-path routing, the meaning of 'could_not_verify' (with error details and that it is not evidence), and 'unsupported', which are important for interpreting results correctly.

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

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

The description is a single, dense paragraph that front-loads natural-language trigger phrases and logically progresses to examples and edge cases. While slightly verbose in places (e.g., the grounded pipeline phrase), every sentence contributes meaningful guidance, making it 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?

Despite lacking an output schema, the description thoroughly covers return values: the verdict set, the actual value with citation, and reasoning, plus error semantics. It also explains what 'unsupported' means and the tool's consolidation of multiple calls, making the tool fully understandable without needing additional docs.

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% description coverage for both parameters, so the baseline is 3. The description adds extra meaning by explaining how 'tolerance_pct' overrides implied defaults and giving a specific use case (hallucination detection with 1–2%), which enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose as natural-language claim verification against authoritative sources, with a specific verb 'validate' and resource 'claim'. It distinguishes itself from sibling tools like ask_pipeworx and compare_entities by focusing on fact-checking and explicit 'true or false' language.

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 usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates between company-financial claims (SEC EDGAR fast path) and other factual claims (grounded pipeline), and notes it consolidates multiple sequential calls, giving clear context for when to select this tool.

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