Datamuse

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

Annotations already indicate a safe read-only, idempotent operation. The description adds useful behavior beyond that: the default free model (Workers AI Llama-3.3-70b), the BYO-API-key requirement for Anthropic with direct payment implications, and the per-model return structure. This gives the agent insight into cost and external call behavior without contradicting the annotations.

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

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

The description is three sentences that front-load the core purpose, then add key details (default model, cost implication, return format, use cases) without any redundant filler. Every sentence contributes necessary 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?

With no output schema, the description compensates by explicitly naming the return structure ('per-model {score, confidence, signals, raw_response} + a combined view'). It also covers the model options, key requirement, and typical usage scenarios, making it complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so parameters are already individually documented. The description adds value by explaining the default behavior (omitting models uses the free workers-ai model), the conditional need for _apiKey (only when 'anthropic' is in models), and the pass-through nature of the key. This relational context goes beyond the static schema descriptions.

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

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

The description clearly states the primary action: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This specific verb-resource combination distinguishes it from siblings like ask_pipeworx (question-answering) and scan_competitor_ai_presence (competitor-focused) by emphasizing a visibility scoring metric.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that tell the agent when this tool is valuable. However, it doesn't explicitly mention when not to use it or name alternative tools, so it stops short of a complete guideline.

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

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

Annotations already give readOnly/idempotent/non-destructive hints. The description adds valuable behavioral context: it routes to one of 5,529 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, is fast, and works on every tier. No contradictions with annotations.

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

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

The description is relatively long but well-structured: it opens with a strong preference directive, enumerates domains, introduces alternatives, and closes with examples. Every section earns its place, though some repetition (e.g., multiple example phrasings) could be trimmed without loss.

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

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

The description covers purpose, usage triggers, alternatives, output format (citations), performance characteristics, and tier compatibility. It does not discuss failure modes or limits, but annotations and output schema absence make this acceptable. The sibling context is well integrated.

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

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

The input schema already documents the 'question' parameter and its aliases with 100% coverage. The description does not add parameter-specific semantics beyond usage examples, but the schema's alias documentation is sufficient. Baseline 3 is appropriate given 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 answers factual questions by routing to a network of verified sources, with a specific list of domains (SEC filings, FDA, FRED, etc.). It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its purpose and scope unmistakable.

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

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

Provides explicit when-to-use guidance: 'START HERE for most questions', 'Use whenever the user asks...' with trigger phrases, plus concrete examples. It also gives alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. This is model-tier guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: it has the same response shape as ask_pipeworx, currently no candidate is active, and results are compared against the stable router. It clearly states it is a full working router with no fallback.

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

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

The description is concise yet comprehensive, covering what the tool is, its current state, how to use it, and its experimental nature. Every sentence contributes distinct value, and the structure is logical and front-loaded with the key identity.

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

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

Given the tool's complexity and lack of output schema, the description is sufficiently complete. It explains the beta nature, the identical behavior to ask_pipeworx, and the current no-active-candidate state. However, it does not elaborate on the response format since it relies on the stable tool's established behavior.

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

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

Schema description coverage is 100%, with all six parameters being aliases for 'question'. The description only says 'same arguments' and does not add any new parameter-level meaning beyond what the schema already provides, which is 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 that this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and arguments. It distinguishes itself from the stable ask_pipeworx and ask_pipeworx_grounded siblings by explicitly positioning itself as the experimental edge with routing improvements.

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

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

The description gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also implies that stable behavior is on ask_pipeworx, but it does not explicitly say when NOT to use this tool or mention alternatives like ask_pipeworx_grounded.

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 safe/read-only behavior is covered. The description adds meaningful behavioral context: same routing as ask_pipeworx, one extra LLM call, refusal reason types, and exact response shape on success/refusal. It does not explicitly mention the openWorldHint, but it explains how evidence is extracted. Almost a 5; slight missing detail on cancellation/rate-limit behavior would push to 5.

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?

Packed but not overly long; provides a clear flow from behavior to use case to trade-off. The first sentence front-loads the purpose. It might be slightly dense with all the technical details (refusal codes, cost), but every sentence adds value. A 5 would require a bit more whitespace/formatting; 4 is appropriate.

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

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

Given there is no output schema, the description fully explains the return shape (answer, evidence, confidence, source, fetched_at, refusal_reason) and all refusal reasons. It also covers the routing behavior and cost trade-off. For a complex tool with many sibling tools, this description is remarkably complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% (all parameters are aliases for question), so schema already documents the parameters. The description adds value by clarifying that the single question is natural language (implicit in 'question in natural language' in schema). It does not enumerate the 5 aliases, but schema does that. This is more than baseline 3 because the description clarifies how the question is used (routed to 5,529 tools, fetched, then grounded extraction). But since the parameters are simple aliases, a 4 feels right.

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?

Uses a specific verb ('answers') and resource ('ask_pipeworx') with a clear qualifier ('grounded' / hallucination-resistant). It distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction and refusal behavior. The phrase 'Hallucination-resistant answer mode for high-stakes reads' clearly states what it does and differentiates it from the plain ask_pipeworx tool.

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 whenever an answer will be quoted, cited, or acted on...' and provides alternatives: 'prefer ask_pipeworx for casual lookups.' It also mentions cost trade-off ('Costs one extra LLM call') and gives examples of high-stakes domains. This is excellent guidance.

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

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

Beyond the read-only/idempotent annotations, the description discloses extensive behavioral details: the resolver contract (low/medium/high confidence, alternatives, suggestions), safety short-circuit on low-confidence matches, blocking behavior for closed/dead markets, wide-spread tradeability warnings, news fallback flags, and resolution-rule risk. This goes far beyond what annotations provide and is critical for safe agent use.

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

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

The description is long but every section earns its place, broken into labeled blocks (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It front-loads the core purpose and usage in the first two sentences, then organizes complex details logically without redundancy.

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

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

With no output schema, the description fully explains return values: market fields, analysis fields, evidence structure, parent_event extractor, news fallback fields, status values, and resolution-rule risk. It covers edge cases (low-confidence, closed markets, wide spreads) and provides actionable instructions (e.g., 'ALWAYS inspect these before trusting'). No gaps remain for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context like the variety of market input formats (slug/URL/question text) and fan-out examples, but these are illustrative rather than new parameter semantics. The schema already documents depth and include_raw descriptions, so the description provides marginal added value.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings like ask_pipeworx (general Q&A) and polymarket_edges (edge scanning) by focusing on market research with evidence fan-out and a market-vs-model comparison.

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

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

Explicit 'Use for' guidance covers 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z', providing clear context for when to invoke. It does not explicitly name alternative tools or describe when-not-to-use, but the use cases are sufficiently specific 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?

Annotations already declare readOnly/openWorld/idempotent, and the description adds concrete behavioral details: data source (SEC EDGAR/XBRL, FAERS/FDA), off-calendar fiscal year handling, sorting by primary metric, and citation URI output. No contradiction; the description enriches the annotation context.

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

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

The description is a single dense paragraph with no wasted words; every sentence adds utility (triggers, data sources, edge-case handling, output format). Front-loaded with user-language examples.

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

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

Despite no output schema, the description specifies return content (paired data + citation URIs), sorting behavior, and entity count limits. Combined with rich annotations and full schema coverage, it fully equips an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond by explaining type semantics ('company' pulls latest 10-K metrics, 'drug' pulls FAERS/FDA counts) and providing value formats (tickers/CIKs vs names) with concrete examples, adding meaning beyond the generic array description.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one call, with explicit trigger phrases. It distinguishes itself from siblings (e.g., entity_profile) by emphasizing parallel comparison vs sequential single-pack lookups.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing direct when-to-use guidance. It also clarifies entity types and data sources, and implicitly excludes single-entity use cases.

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

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

Beyond the readOnly/idempotent annotations, the description richly discloses behavioral traits: decomposition into facets, parallel routing to 5,529 tools, return packet structure with gaps[] and contradictions[], citation URI only when resolvable, semantic excerpting, and latency expectations of 15-90s. 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 lengthy but every sentence carries meaningful content. It is front-loaded with the critical account requirement and core purpose, then flows into usage guidance. For a complex tool with multiple depth tiers and return fields, the length is justified, though slightly more concise phrasing could trim 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 no output schema, the description fully explains the return values (findings packet with fields, gaps[], contradictions[], hop field, citation_uri) and covers failure modes, latency, account requirements, and depth-specific behavior. This is a complete picture 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 for both parameters (question, depth) is 100%, so the baseline is 3. The description reinforces depth semantics and adds context about multi-part questions, but does not introduce new parameter meaning beyond the detailed enum descriptions already present in the schema.

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

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

The description clearly states the tool performs grounded multi-source research across 1455 structured data sources in one call, using specific verbs and resources. It distinguishes itself from sibling tools by explicitly noting 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and explicitly names alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also covers account prerequisites and when to use each depth tier.

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 and idempotent hints. The description adds valuable behavioral context: returns top-N tools, includes names/descriptions/full schemas with curated examples, and each result is ready to call directly without a second lookup. This goes beyond the structured annotations.

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

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

The description is front-loaded with the core purpose, and every sentence adds information. The long list of domains is somewhat repetitive but serves as a quick reference for users. It is slightly longer than strictly necessary but remains efficient and well-structured.

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 6 parameters and no output schema, the description covers the essential context: what the tool returns (names, descriptions, schemas, examples), how results are ranked (top-N), and when to invoke it. It does not mention edge cases like no matches or error handling, but for a discovery tool with strong annotations this is sufficient.

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

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

Schema description coverage is 100%, so the schema fully explains all parameters including aliases and the natural language query format. The description adds no parameter-specific semantics beyond what the schema already states; it mentions 'describing the data or task' and 'top-N' but these are already implied by 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 opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly states this is a discovery/search tool, distinct from siblings that perform analysis or retrieval. It enumerates supported domains, which further clarifies 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: 'Use when you need to browse, search, look up, or discover what tools exist.' It also gives strong call-first guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This implies when not to use (when you already know the specific tool), providing a clear usage boundary.

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

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

Beyond the readOnly/idempotent annotations, the description discloses key behaviors: parallel fan-out across multiple sources, number of filings (up to 5), sorted fundamentals, the USPTO PatentsView sunset leading to soft-fail, and the GDELT→GNews fallback for news. This is rich behavioral context.

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

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

Though detailed, every clause earns its place: trigger phrases, core function, return sections, source list, input constraints, and fallback behavior are all packed in without bloat. It's well-structured for a complex multi-source tool.

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

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

With no output schema, the description compensates fully by enumerating every return section (cik, company_name, recent_filings, fundamentals, patents, news, LEI). It also covers edge cases (soft-fail, ticker vs CIK, names unsupported). 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 already covers both parameters (type and value). The description adds concrete examples and clarifies zero-padded CIK format, plus reinforces the names-not-supported rule. While the schema descriptions are clear, the examples and zero-padding note add practical semantics.

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

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

The description opens with multiple user-intent examples, then states the core function with a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' It explicitly distinguishes itself from sibling tools like chaining single-pack lookups and from resolve_entity (by clarifying names are not supported).

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

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

It gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also mentions the alternative for name-only queries: 'use resolve_entity first if you only have a name.' Clear and actionable.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds contextual behavior: it explains the purpose (clearing stale or sensitive data) and the pairing with remember/recall, which goes beyond the annotations. No contradiction exists.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds value. The use-case guidance and sibling reference are concise without unnecessary detail. It wastes no words.

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

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

For a one-parameter tool with strong annotations (destructive, idempotent) and no output schema, the description covers the essential use cases and complements the schema. It even references related tools (remember, recall) to provide workflow context, making it fully complete for the tool's complexity.

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

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

The input schema already describes the only parameter: 'key' with 'Memory key to delete.' With 100% schema coverage, the description's 'by key' adds minimal extra meaning. It doesn't provide additional format or examples beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with a specific action: 'Delete a previously stored memory by key.' This clearly identifies the resource (memory) and the operation (delete), distinguishing it from siblings like remember (store) and recall (retrieve). The verb 'delete' is 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 use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, which situates it within the memory workflow. It doesn't explicitly say when not to use it, but the guidance is strong enough for tool selection.

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

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

The description details the operational behavior: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This adds value beyond the annotations (readOnlyHint, idempotentHint) by explaining the pipeline and output format. Annotations already cover safety, but this description enriches understanding without contradicting them.

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

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

The description is three sentences, front-loaded with the action, then the process, then concrete use cases. No redundant filler; each sentence earns its place. This is an exemplar of concise, structured tool documentation.

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 only 2 parameters and no output schema, the description covers everything needed: input (URL), options (max_links is inferred by 'key links'), process, output format ('single text blob'), and deployment location. The use-case list adds context about applicability. There are no gaps given the tool's simplicity.

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

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

The input schema already provides complete descriptions for both parameters (url and max_links), and schema coverage is 100%. The tool description itself does not add new parameter-specific semantic details beyond what the schema offers, so it meets the baseline without exceeding it.

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

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

The description uses a specific verb-resource pair: 'Generate a production-ready llms.txt file for any URL.' It clearly states the deliverable (llms.txt file) and the purpose (helping AI crawlers index the site). It also distinguishes from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence' by focusing on file generation rather than auditing or checking.

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

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

Provides clear use cases ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving a solid sense of when to invoke it. It does not explicitly name alternatives or exclusions, which prevents a 5, but the context is clear enough for an agent to decide.

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, destructiveHint, and idempotentHint. The description adds useful context by specifying the return fields (id, type, params, created_at, etc.) and the 'caller's' scoping, which is beyond what annotations provide.

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

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

Two sentences, no fluff. The first sentence states purpose and output fields; the second gives actionable usage guidance. Every word earns its place.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers purpose, return data, and usage context. It is complete and well-rounded.

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 coverage is 100%, with include_inactive already fully described. The description does not add any extra meaning for this parameter, so it meets the baseline but does not exceed it.

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

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

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

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

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

It gives explicit use cases: to review what you're monitoring before adding more, and to find an id to cancel. While it doesn't explicitly name alternative tools, it implicitly references subscribe and unsubscribe, providing clear context for when to use this tool.

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

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

With all annotations false, the description carries the transparency burden. It discloses the rate limit ('5 per identifier per day'), the claim_token lifecycle (filing returns a token; passing it later reads the fix status), and privacy guidance ('don't paste the end-user's prompt'). It also clarifies cost ('Free; doesn't count against your tool-call quota'), but doesn't explicitly state that submitting creates a persistent record, so a 4 is appropriate.

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?

While long, the description is highly structured and front-loaded with the primary purpose. Each sentence adds critical context (types, exclusions, token workflow, rate limits, cost), and there is no padding or repetition of schema content. It reads as a single essential briefing for agents.

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 4 parameters, a nested context object, and no output schema, yet the description covers the return value (claim_token), optional context fields, message constraints, and invocation pattern. It also scopes to Pipeworx-only tools, preventing misuse, and includes practical guidance on how to structure feedback — making it complete for both selection and invocation.

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

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

Schema coverage is 100%, and each parameter already has a detailed description. The tool description goes beyond the schema by providing a concrete claim_token invocation example (`pipeworx_feedback({claim_token:"pwfb_…"})`), explaining that message should be 1-2 sentences, and clarifying that context is optional structured metadata — adding meaning the schema leaves implicit.

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, action-oriented statement ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates specific feedback categories (bug, feature/data_gap, praise). It also explains the claim_token retrieval workflow, fully differentiating this from sibling research/query 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 states when to use the tool for each feedback type ('Use when a tool returns wrong/stale data... feature/data_gap... praise') and provides exclusion criteria for tools from other MCP servers ('if the tool came from a different MCP server... file it with that server instead'). It also offers a fallback check for identifying Pipeworx tools, making the usage guidance unambiguous.

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

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

Beyond the readOnly/idempotent annotations, the description adds valuable behavioral context: it is derived from CF analytics-engine, contains no PII, returns only (pack, tool, count), and is cached 5min-1h. This sets clear expectations about data freshness, privacy, and output shape.

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

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

The description is well-structured and front-loaded, starting with the main purpose. It includes a useful numbered list for usage cases and ends with technical details. It is slightly longer than necessary but every sentence contributes 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 simple read-only tool with one optional parameter, the description covers all essential aspects: what it does, what it returns, caching, privacy, and usage context. The absence of an output schema is adequately compensated by describing the return format.

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

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

The schema fully describes the `window` parameter with enum values and guidance about short vs. long windows. The description only mentions the same window options without adding new meaning, so the baseline of 3 for high schema coverage is appropriate.

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

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

The description clearly states the tool's function: showing what other AI agents are calling on Pipeworx right now, with specific outputs (top tools, top packs, total call volume). The 'trending' scope gives it a distinctive identity among the sibling tools, and the verb+resource structure is specific.

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

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

The description lists three concrete use cases with numbered items, explaining when to use the tool (discovering hot data sources, confirming canonical choice, seeing alignment). It doesn't explicitly name alternatives, but the situational guidance is strong and contextual.

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 safety hints (read-only, non-destructive), but the description goes far beyond: it discloses >3pp threshold, ≥0.30 Jaccard similarity, placeholder filter rules, and fill-check behavior against live CLOB depth, including 'realizable_edge_pp ≤ 0 means do not trade it.' No contradiction.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every detail earns its place, though a slightly tighter presentation would improve scannability.

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

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

Even without an output schema, the description specifies the response shape, edge cases, and failure conditions. It also connects to related tools for fill risk, making it self-sufficient for an agent to invoke correctly.

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

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

The schema already covers 100% of parameters, but the description adds practical examples (e.g., 'fed-decision-may-2026') and explains mode-specific behaviors. It adds semantic value beyond schema descriptions, though not a full replacement for structured docs.

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' clearly stating the verb, resource, and method. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on cross-market arbitrage detection.

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

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

It provides explicit invocation modes (no args for trending_scan, event for specific market, topic for cross-event), with recommendations and examples. It also points to the alternative polymorphic_fill_risk for custom sizing, making usage boundaries 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 only declare readOnlyHint=true, idempotentHint=true, etc., but the description goes far beyond: it details model families, response segments, edge calculation (net of slippage), Kelly caps, placeholder filters, 24h-move warnings, caching behavior, and diagnostic fields. It also discloses limitations (e.g., unreliable Fed signal without paid data) and design quirks (partition kelly_fraction_half=0 by design). This is exceptional transparency.

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 structured with capitalized sections (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and dense, non-redundant sentences. It front-loads the core purpose and then provides necessary complexity. While it could be trimmed, every sentence adds value for an agent making nuanced decisions; the length is justified by the tool's complexity.

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

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

Despite no output schema, the description fully specifies the response structure: top-level by_segment groups, fed_candidates/fed_note, and _diagnostics with funnel counters and filter_skips. It explains what each opportunity carries (edge_pp_net, kelly_fraction, liquidity, spread_pp, etc.) and why diagnostics exist. This is a complete picture for an agent to interpret results and handle empty segments correctly.

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

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

The schema already covers all 9 parameters with descriptions, but the top-level description adds meaningful semantics: e.g., min_edge_pp is 'NET of slippage', min_partition_leg_kelly explains the per-leg Kelly logic and why min_kelly doesn't apply to partitions, and slippage_pp includes rationale about Polymarket fees and spread. These extras go beyond the schema, though not every parameter receives additional commentary.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly identifies the tool's function and differentiates it from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on discovery from Pipeworx data disagreement. The stated use case 'what should I bet on today' further anchors its 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 implies when to use the tool ('agents discover opportunities without paging hundreds of markets') and provides context on its design. However, it does not explicitly state when not to use it or name alternative tools for other scenarios, so it doesn't fully satisfy the 'explicit exclusions/alternatives' bar. The detailed knob explanations and Fed-bets caveat provide solid usage context.

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

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

Even with annotations already declaring readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral context: 60-day snapshot TTL, snapshot gaps due to cache-miss behavior, decay computed from daily closes rather than intraday, and the meaning of `expired[]`. These details go well beyond the annotations and fully disclose limitations.

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

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

The description is long but exceptionally well-structured, with labeled sections for `ARG`, `RESPONSE`, and `LIMITS`. The opening sentence is a concise summary, and every subsequent statement adds unique value. The density of information justifies the length, and it is front-loaded with the most important purpose.

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

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

For a tool with no output schema, the description thoroughly explains the response format (tracked[], expired[], snapshot_dates[]) and the key limitation (history bounded by 60-day TTL). It covers data sources, edge-case behavior, and even interprets metrics like median lifespan. This is effectively a complete virtual schema for the return value.

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 both `days` and `window`. The description reinforces the defaults and clamps but also adds semantic nuance: `window` is called a 'snapshot family' and `days` is explicitly a 'lookback'. This enriches the parameter understanding beyond the 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 a specific, action-oriented statement: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers a distinct question ('how long has this edge existed and is it shrinking?') that differentiates it from sibling tools like polymarket_edges, which likely shows current edges. This is a precise verb+resource+scope definition.

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 a clear use case: distinguishing a fresh wide edge from a stale one ('a fresh wide edge and a 3-week-old wide edge are different trades'). It implies when to use this tool, but it does not explicitly name alternatives or state when NOT to use it. This is strong contextual guidance but lacks explicit exclusions.

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

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

Beyond the readOnlyHint, the description discloses detailed behavioral traits: mode-specific logic ('walks the ladder'), interpretation of parameters ('max spend on buys, target proceeds on sells'), return values (top_of_book, vwap_fill_price, etc.), and risk warnings (forced_directional_risk). This far exceeds what annotations provide and helps the agent understand side effects and outputs.

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

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

The description is long but every sentence earns its place. It is clearly structured: general statement, single-market mode, basket mode, and usage guidance. It avoids redundancy and presents complex information in a scannable, logical order.

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 parameters and no output schema, the description is remarkably complete. It covers both modes, parameter semantics, return fields, edge cases (thin_legs, forced_directional_risk), and the exact scenario where the tool should be used. The agent has all necessary context to invoke it correctly.

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

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

While schema coverage is 100%, the description adds substantial semantic meaning: default values, mode-dependent interpretations (size_usd as spend vs. proceeds vs. settlement notional), and the exact effect of side values in basket mode (sell_yes for overround, buy_yes for underround). The description enriches each parameter significantly 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a specific verb+resource statement that clearly defines the tool's purpose. It also distinguishes itself from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges in the usage guidance.

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

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

Usage guidance is explicit: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when the tool is necessary (theoretical overround on thin books is not capturable, partial fills create directional risk), making the decision to use it 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 and non-destructive, but the description goes far beyond by detailing compatibility_warning conditions, temporal_alignment, and skipped_cross_type counters. It transparently discloses that most pre-mapped topics return warnings, setting accurate 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?

The description is long and dense, but well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS). Every detail earns its place for a complex tool, though it could be tightened slightly to avoid overwhelming agents.

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

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

Given the complexity and absence of an output schema, the description thoroughly covers response fields, safety warnings, temporal alignment, and skipped-leg counters. It leaves no critical ambiguity about how to interpret results or when to trust them.

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 descriptions for each parameter, but the description adds critical semantics about how topic, kalshi_event_ticker, and polymarket_event_slug interact (overrides, two modes). It also enriches the topic parameter by listing the 10 shortcuts and explaining that explicit tickers override the mapped sides.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses a specific verb ('spread') and resource, and distinguishes itself from same-venue arbitrage tools by emphasizing the cross-venue nature and two operating modes.

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

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

The description explains when the spread is meaningful (when bet shapes are equivalent) and when it is not (compatibility_warning), and distinguishes between pre-mapped and explicit modes. However, it does not explicitly name sibling alternatives like polymarket_arbitrage, so the guidance is clear but not directly comparative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds extra behavioral context by noting scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the behavior of listing all keys when the key argument is omitted. 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 concise but information-dense. Three sentences cover purpose, use cases, scoping, and relationships to siblings. Every sentence earns its place without fluff.

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

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

Given the tool's simplicity (one optional parameter) and rich annotations, the description is complete. It explains the tool's role, behavior, and usage context. No output schema exists, but the description implies retrieval results and the listing behavior, which is sufficient for this low-complexity tool.

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

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

The schema has 100% coverage for the single parameter, describing 'key' as 'Memory key to retrieve (omit to list all keys)'. The description repeats this semantics ('omit the key argument') and adds context about what the key represents (e.g., 'user's target ticker, an address'), but does not add meaning materially 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 explicitly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb (retrieve/list) and resource (saved values), and distinguishes itself from the sibling tools 'remember' and 'forget' by naming them.

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

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

The description provides clear when-to-use guidance: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also explicitly relates to alternatives: 'Pair with remember to save, forget to delete,' which clarifies the tool's role 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 readOnlyHint=true, but the description discloses the mark_read side effect that flags events read, which adds nuance beyond the annotation. It also explains the feed location (persisted, registry URL) and that the same feed is available externally, though it doesn't cover rate limits or error behavior.

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

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

Three sentences, front-loaded with the core action ('Pull fired events'), and every sentence adds meaningful detail without redundancy. Efficient and easy to scan.

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 presence of annotations and a complete schema, the description sufficiently covers purpose, return data, filtering options, side effects, and an alternative access method. It is self-contained for an agent to decide when to invoke and what to expect.

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

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

Schema covers all 5 parameters with descriptions, so baseline is 3. The description adds value by providing a concrete type example ('sec_8k') and clarifying that 'since' takes an ISO timestamp, plus explaining the mark_read side-effect in plain language, going slightly beyond schema.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifies the return payload (source, citation_uri, raw event), and mentions filtering. This distinguishes it from sibling tools like list_subscriptions or recent_changes by focusing on alerts and their contents.

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

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

It gives explicit context for when to use the tool (polling, filtering by type/since, marking read) and even suggests an alternative HTTP endpoint for scripts. However, it does not explicitly say when not to use it relative to other alert-related tools, so it lacks formal 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 behavior, but the description adds valuable context beyond them: source fan-out to SEC EDGAR, GDELT→GNews fallback with rate-limit/5xx conditions, USPTO soft-failure due to API sunset, and the return structure. There is no contradiction with annotations.

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

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

The description is well-structured and front-loaded with purpose and example queries, and every major aspect earns its place. However, the string of natural-language phrasings ('What's new with X' / 'latest on Y' / etc.) is somewhat redundant and could be condensed without losing meaning.

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 multi-source aggregation tool with no output schema, the description is remarkably complete. It covers all data sources, fallback behavior, failure mode (USPTO sunset), and the exact return structure (changes[] grouped by source, total_changes, citation URIs), which is more than sufficient for selection and invocation.

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

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

Although schema coverage is 100%, the description adds meaningful enrichment: `since` is clarified with ISO and relative shorthand examples, `value` is explained as ticker or zero-padded CIK, and `type` is confirmed to only support 'company.' This goes beyond the schema descriptions and helps correct invocation.

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

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

The description opens with concrete user-phrase examples and clearly defines the tool as a change feed for a company over a time window, aggregating filings, news, and patents in one parallel call. It also distinguishes itself from entity_profile by explicitly naming that alternative, making the tool's purpose highly specific and clear.

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

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

The description provides clear trigger phrases and states it runs 'in ONE parallel call,' establishing when to use it. It also gives an explicit exclusion: 'Use entity_profile instead when you want the static profile... regardless of window.' This provides clear when/when-not guidance relative to a key sibling tool.

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

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

Annotations already set readOnly=false, destructive=false, and idempotent=true. The description adds behavioral context about persistence: authenticated users get persistent memory while anonymous sessions last 24 hours, and that it is scoped by identifier. However, it does not disclose overwrite behavior when a key already exists, but the idempotent hint partially covers that.

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

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

Three sentences, front-loaded with the action, includes use cases, storage model, and companion tools. Every sentence adds value with no redundancy.

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

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

For a simple two-parameter tool with no output schema and clear annotations, the description covers purpose, usage, persistence semantics, and related tools. It is complete for this complexity level.

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

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

The schema already fully describes both key and value with examples (100% coverage). The description reinforces the value type with 'findings, addresses, preferences, notes' but does not add significant semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description uses the specific verb 'save' plus the resource 'data the agent will need to reuse later,' and explicitly differentiates from sibling tools recall and forget by naming them as companions. This clearly states the tool's function and distinguishes it from alternatives.

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

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

It provides explicit guidance: 'Use when you discover something worth carrying forward...' and gives concrete examples (ticker, address, preference, research subject). It also mentions pairing with recall and forget, clarifying the workflow. This clearly tells when to use the tool.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds valuable behavioral details: it cascades through multiple endpoints, degrades gracefully if GLEIF/OpenFIGI are unavailable, labels each identifier with its source, and explicitly reports unresolved identifiers. These operational traits are not inferable from the schema and materially affect how an agent can rely on the result.

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 is front-loaded with user-facing examples and a clear core statement. It is organized into support types and includes only functional details; no filler is present. However, it could be tightened by moving detailed enrichment fallback behavior into a separate note.

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?

Because there is no output schema, the description carries the burden of explaining return values. It lists exact fields returned for both company and drug types (CIK, ticker, LEI, FIGI, RxCUI, etc.), covers unresolved-identifier handling, and explains the multi-lookup cascade. This gives a complete mental model for an agent.

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

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

The schema covers both parameters descriptively, but the description enriches them with concrete examples ('AAPL', '0000320193', 'ozempic') and clarifies accepted formats (ticker vs CIK vs name for company; brand vs generic for drug). This helps agents construct valid values with less risk of error.

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

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

The description uses a concrete verb ('resolve') with a clear object ('user-spoken NAME to canonical/official identifiers'). It includes example queries and explicitly contrasts with sibling tools like compare_entities/entity_profile by directing agents to use this tool FIRST when needing an ID. This strongly establishes scope and differentiates it from alternatives.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID', giving a decisive when-to-use rule. It also details what types of inputs are accepted for each entity type, helping agents decide if it's the right tool. While it doesn't list specific alternative tools, the guidance is sufficient.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses that the tool internally calls ai_visibility_check for each entity, ranks by score, and returns a ranked list with score, confidence, and signal density. This adds process-level transparency without contradicting the annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, followed by a concrete use case and a clear statement of the output. Every sentence earns its place with 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 tool with four parameters and no output schema, the description covers the purpose, internal process, typical usage context, and return format (ranked list with score, confidence, signal density). It does not delve into edge cases or failure handling, but it provides sufficient context for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, with all four parameters (models, _apiKey, context, entities) already richly described in the schema. The tool description repeats some of this (e.g., first entity as subject) but adds no new parameter semantics beyond what the schema already provides, justifying the baseline score 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: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from the sibling ai_visibility_check by explicitly mentioning it probes each entity with that tool and then ranks results, making the scope and differentiation obvious.

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 frames the use case as 'competitive AI-marketing audits' and provides an example query ('does Claude know about us as well as our competitors?'), which signals when to use it. It implies that single-entity checks would use ai_visibility_check, but it does not explicitly state exclusions or alternatives beyond that.

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

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

While annotations already signal readOnly/idempotent/openWorld, the description adds substantial behavioral detail: it is a composite fan-out call, bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully, and sources_failed will note timeouts. This goes well beyond the annotation hints and tells the agent what to expect at runtime.

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?

It is a dense paragraph but every sentence earns its place: the headline composite purpose, concrete usage trigger, return payload summary, ecosystem boundary, and graceful-degradation behavior. The front-loaded sentence immediately conveys the tool's value.

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

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

With no output schema, the description takes responsibility for explaining results—it enumerates the summary block fields, per-advisory detail, links, and recent alternatives. It also covers failure modes, latency, and scope, making the tool usable without further documentation.

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

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

Schema coverage is 100% and the schema already explains both parameters (package name and version default). The description adds only a usage example ('lodash') and the return field list, but no additional parameter-level meaning, so it holds the baseline for high schema coverage.

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

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

The description opens with a clear, specific purpose: a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. This verb+resource+scope formulation distinguishes it from the sibling research and visibility tools, and the NPM-only scope is explicitly stated.

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

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

It explicitly says 'Use whenever an agent asks ...' and names concrete queries ('is X safe / popular / small', 'what does adding lodash cost me'). It also excludes non-NPM ecosystems and points to an alternative ('deps.dev:version directly').

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 several behavioral traits beyond the annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation and flagging, and the return structure (character offsets and similarity scores). This is substantial technical context and there is no contradiction with the readOnly/idempotent hints.

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

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

The description is dense but well-structured, front-loaded with the core function, then use-case, pairing info, and technical details. Every sentence provides distinct value; 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 (semantic search), the description covers the full operational picture: input requirements, return format (offsets/similarity), technical constraints (200K cap, truncation), and integration with a sibling tool. No output schema exists, but the description adequately explains the return values. This is exceptionally complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic enrichment beyond the schema: 'text' is contextualized as 'already pulled' content (e.g., SEC 10-K body), 'query' as natural-language with examples, and 'limit' as 'top-N passages.' This clarifies practical usage without duplicating schema text.

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

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

The description opens with a specific verb+resource pair: 'Semantic search INSIDE a fetched record.' It clearly states the tool's function (pass text + query, get top-N passages with offsets and similarity scores) and differentiates it from sibling tools by emphasizing 'inside a fetched record' and referencing ask_pipeworx_grounded as a complementary tool.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also provides a concrete alternative/companion workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear context and exclusions.

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

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

Discloses substantial behavior beyond annotations: OAuth requirement, always-on feed, optional email/SMS/webhook delivery with verification and caps, webhook HMAC signing, one-time secret return, and auto-disable after 10 consecutive failures. Annotations (readOnlyHint=false, idempotentHint=true) are consistent; the description adds deep operational context without contradiction.

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

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

The description is a single dense paragraph but front-loaded with the core action and then logically organized (auth, types, channels). Every sentence provides useful information, though the length is near the upper bound for a concise definition. It could be slightly more scannable with bullets, but it remains efficient.

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

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

Given the complexity (3 parameters, nested objects, 5 types, multiple delivery channels, no output schema), the description is remarkably complete. It covers prerequisites, return value, type-specific parameter examples, delivery options with constraints, and failure behavior (webhook auto-disable). No critical gap is apparent for an agent deciding to invoke the tool.

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

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

Schema description coverage is 100%, and the schema itself contains detailed per-type examples and delivery field explanations. The description largely repeats this information (e.g., items:["5.02"] = officer change, phone verification). While it adds a few context clues (e.g., 'proactive monitoring'), the schema already carries the semantic load, so the description adds marginal value beyond the baseline.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream' and states the return value ('Returns the new subscription id'). This clearly distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides clear context: requires a Pipeworx OAuth account, enumerates supported types, and explains delivery channel prerequisites (e.g., phone verification, 10/day SMS cap). It does not explicitly name alternative tools for viewing or deleting subscriptions, but the context signals (sibling names) imply those alternatives. The absence of explicit 'when not to use' guidance keeps it slightly below 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 the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by explaining the return structure (category-bucketed examples with tool+argument shapes) and that it draws from a live catalog of thousands of tools. It does not contradict any annotations.

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

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

The description is a single paragraph that efficiently captures capability, usage, and customization in a front-loaded format. It begins with example user phrasings, then concisely explains the return structure and invocation options without redundancy.

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

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

Given the simple schema (1 optional param), strong annotations, and no output schema, the description is fully complete: it covers what the tool returns, how to scope it, and when to use it. The absence of an output schema is mitigated by the description's explanation of the category-bucketed response format.

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

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

The schema fully documents the single optional `topic` parameter (100% coverage), so baseline is 3. The description enhances this by providing concrete example values ('finance', 'pharma', 'betting') and explaining the effect of omitting it (full spread), adding value beyond the schema.

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

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

The description explicitly states the tool's purpose as the onboarding entry point for discovering what to ask Pipeworx, returning category-bucketed example questions with exact tool and argument shapes. It distinguishes from siblings like ask_pipeworx by focusing on suggestions rather than execution.

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 directly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you,' and mentions learning to call meta-tools like ask_pipeworx, entity_profile, and compare_entities. It also explains how to use the optional topic parameter for focused queries, giving clear when-to-use guidance.

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

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

The description goes beyond annotations by explaining that the row is deactivated not deleted, ownership is enforced, and historical events remain available via recent_alerts. This is exactly the kind of behavioral context that helps agents anticipate side effects.

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

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

Two sentences, front-loaded with the action, then key constraints. Every sentence contributes meaning without any 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?

For a simple one-parameter mutation with strong annotations, the description is complete: it clarifies what happens (deactivation, not deletion), the ownership condition, and the relationship to recent_alerts. No output schema means return values aren't required.

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

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

The input schema already has a clear description for 'id' ('Subscription id (uuid) returned by subscribe'), and the description only says 'by id', adding no new parameter meaning. High schema coverage means the description doesn't need to compensate.

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

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

The description opens with 'Cancel a subscription by id', a specific verb+resource combo. It distinguishes itself from sibling tools like subscribe and list_subscriptions, and the ownership enforcement adds clarity.

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

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

Usage context is implied: this tool cancels subscriptions, and the ownership enforcement tells users they can only cancel their own. It doesn't explicitly name alternatives, but the behavior details (deactivation, recent_alerts) guide use cases.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, so the bar is lower. The description adds critical behavioral nuance beyond those annotations: it explains that 'could_not_verify' means the check did not happen, carries verification_error, and must not be treated as evidence; it also defines 'unsupported' and describes the two execution paths. This is exactly the kind of context that prevents misuse.

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

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

The description is dense but every sentence earns its place: trigger phrases, scope, pipeline routing, return values, and the critical could_not_verify/unsupported distinction. It is front-loaded with user intent and ends with operational caveats, with 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?

There is no output schema, so the description must explain return values, and it does thoroughly: verdict list, actual value with pipeworx:// citation, reasoning, and the semantic difference between could_not_verify and unsupported. It also covers claim type routing and the fact that this tool consolidates multiple steps, giving the agent enough to invoke and interpret correctly.

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

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

Schema coverage is 100% and both parameters have detailed schema descriptions, including examples, ranges, overrides, and defaults. The description reinforces tolerance behavior with 'exact percent-delta math' but does not add new parameter-level information beyond what the schema already provides. Baseline 3 is appropriate when the schema carries the full 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 opens with natural-language trigger phrases and explicitly states the tool performs 'natural-language claim verification against authoritative sources.' It clearly differentiates the tool from siblings by outlining two distinct pipelines (structured SEC EDGAR for financial claims, grounded pipeline for all else) and by noting it replaces 4–6 sequential calls. This gives a specific verb+resource+scope and distinguishes it from query-oriented siblings.

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

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

The description gives an explicit directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further clarifies routing (financial vs. other claims) and implies this single call replaces composing multiple lower-level tools. It does not explicitly name alternative tools, but the scope is sufficiently self-contained and explanatory.

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