Quiver

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

Annotations (readOnlyHint, etc.) are complemented by description detailing probing behavior, scoring (0-100), return shape per model, free vs paid (Anthropic BYO key), and that Anthropic calls are direct. No contradictions.

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

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

Two well-structured sentences, front-loaded with purpose and key details. No fluff, every sentence earns its place.

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

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

Despite no output schema, description specifies return shape (per-model {score, confidence, signals, raw_response} + combined view). Input parameters fully covered. Includes cost implications for Anthropic. Complete for tool 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% with adequate descriptions. Description provides minor additional context (examples for entity, supported models, purpose of _apiKey). Baseline 3 as schema already does heavy lifting.

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

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

Description clearly states verb 'probe' and resource 'LLMs for visibility scoring', with specific examples (business/brand/product/topic). Differentiates from siblings like scan_competitor_ai_presence by focusing on scoring visibility per model.

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 lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Notes default model and optional Anthropic key. Could mention when not to use, but context signals imply appropriate scenarios.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: it routes to 5,462 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and notes it works on every tier with one fast call. This goes well beyond the annotation baseline.

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

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

The description is long but well-structured and front-loaded with the most important directive ('PREFER OVER WEB SEARCH'). Every section earns its place: use cases, examples, alternatives, and caveats. Slightly verbose with the enumerated domains, but this detail supports a broad router 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?

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It states the return format (structured answer with citations), the router behavior, when to use alternatives, and provides concrete examples covering diverse domains. No critical gap for selecting and invoking this tool.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for the same natural-language 'question'. The description adds examples of valid questions but does not add deeper parameter-level semantics beyond what the schema already provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: answering factual questions about real-world entities, events, and numbers by routing to verified sources. It uses specific verbs like 'PREFER OVER WEB SEARCH' and 'Routes' and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and specifically names alternatives ('ask_pipeworx_grounded', 'deep_research') for cases that need grounded answers or broad fan-out. It also clarifies breaking-news 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?

The description discloses the experimental nature, live candidate testing mechanism, current inactive state, and that it falls back to nothing—being a full working router. This adds substantial context beyond the readOnly/openWorld/idempotent annotations, explaining the beta label and how routing decisions are made.

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 composed of four dense sentences, each serving a distinct purpose: identifying the beta nature, stating current equivalence, giving usage instructions, and explaining fallback. While slightly wordy with specific numbers and dates, the information is all relevant and front-loaded with the tool's 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 annotations and full schema coverage, the description provides essential context about the beta status and experimental comparison, which is necessary for an agent to decide between ask_pipeworx_beta and the stable ask_pipeworx. It covers behavior, usage, and limitations (no fallback) sufficiently for this tool, though it could detail the routing comparison process further.

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

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

The input schema fully documents each parameter with descriptions (all aliases and the required question), giving 100% coverage, so baseline is 3. The tool description does not add parameter-level detail, but the schema already provides complete semantics, so no deduction is warranted.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,462 tools, arguments, and response shape, with candidate routing improvements. It distinguishes itself from the stable ask_pipeworx and the grounded variant by explicitly framing it as the experimental edge.

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

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

It explicitly instructs to 'use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared to the stable router to decide merges. It also clarifies that with no active candidate, it currently matches ask_pipeworx exactly, offering concrete 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?

Annotations declare readOnlyHint, openWorldHint, and idempotentHint. The description adds that it is hallucination-resistant, makes an extra LLM call, returns a structured response with evidence and specific refusal reasons, and refuses when data doesn't contain the answer. This goes beyond the annotation safety profile and fully discloses behavior.

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

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

The description is dense with information: it starts with a clear one-line summary, then explains mechanism, return format, refusal reasons, use cases, and cost tradeoff in a structured sequence. No sentences are wasted.

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 success return fields ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and all refusal reasons, covers edge cases (data not in source), and provides usage context (high-stakes but costly). This is complete for a read-only tool with detailed annotations.

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 'question' parameter and all aliases at 100% coverage. The description does not add specific parameter guidance; it only mentions that arguments are filled internally, which is behavior rather than parameter semantics. Thus, the baseline score of 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads', a specific verb-noun pairing that immediately distinguishes it from the sibling ask_pipeworx. It further clarifies the scope by detailing the extraction process and refusal conditions, making the tool's purpose unambiguous.

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

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

Explicitly states 'Use whenever an answer will be quoted, cited, or acted on' and contrasts with 'prefer ask_pipeworx for casual lookups', naming the alternative and cost tradeoff. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes far beyond these by detailing fan-out behavior, response shapes, resolver contract, parent event extraction, news fields, safety short-circuits, closed market handling, illiquid spread warnings, and resolution-rule risk. It provides deep behavioral 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 lengthy but information-dense, with every sentence adding value. It is front-loaded with the core purpose and examples. However, it could benefit from structural improvements like bullet points or sections to improve scannability. Still, it is appropriately sized for the complexity.

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

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

Given the tool's 3 parameters, rich behavior, and no output schema, the description is extraordinarily complete. It covers edge cases (low-confidence matches, closed markets, wide spreads), resolution-rule risk, parent events, news fallback mechanisms, and even provides response shape details. No gaps are apparent.

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 all 3 parameters described. The description adds significant meaning beyond the schema: it explains that 'market' can be slug, URL, or question text; describes the 'depth' enum values (quick vs thorough) with default; and elaborates on 'include_raw' with use cases. This is exemplary parameter documentation.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and the output (evidence packet + comparison). This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides extensive examples of fan-out per category and includes safety caveats. However, it lacks explicit 'do not use when' guidance, which would be a minor improvement.

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

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

Annotations already indicate a safe, read-only, idempotent tool. The description adds valuable context: data sources (SEC EDGAR, FAERS), correct handling of off-calendar fiscal years, sorting by primary metric, and output format (paired data with URIs). 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 concise (about 6 sentences) and front-loaded with key usage patterns. It efficiently conveys essential details without unnecessary fluff, though slightly more compact could be achieved.

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

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

Given no output schema, the description adequately covers return values (paired data, citation URIs) and data sources. It misses potential details like pagination or recency limits, but for a comparison tool the provided info 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 coverage is 100%, but the description goes beyond by explaining what data each 'type' retrieves (financials for company, clinical data for drug) and clarifying 'values' input format (tickers vs drug names). This adds significant meaning for 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 clearly states that the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific data types for each. It includes trigger phrases like 'Compare X and Y' and distinguishes itself from sequential single-entity lookups among sibling tools.

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

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

Explicit guidance is provided: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Examples of when to use (e.g., 'which is bigger', 'rank these') are listed, making it easy for the 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?

The description goes far beyond the annotations by explaining decomposition into facets, parallel routing to 5,462 tools, the findings packet structure with verbatim evidence, confidence, source, fetched_at, and citation URIs. It discloses gaps[] for unanswered facets, contradictions[] for standard/thorough, semantic excerpting, latency expectations, and the hop field. This is rich behavioral context that annotations (readOnlyHint, openWorldHint, idempotentHint) don't provide.

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

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

The description is dense and information-rich, front-loading the critical account requirement at the very start. Every sentence adds value, covering data sources, use cases, exclusions, depth tiers, output format, citation behavior, and latency. While long, it is well-structured with semicolons and clear topic shifts, earning its length.

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

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

Given the tool's high complexity (2 params, no output schema, but rich behavior around decomposition, parallelism, gap recovery, contradictions, citations, excerpts, and pricing), the description is remarkably complete. It tells the agent what to expect in the return (findings packet with specific fields), how long to wait, what gaps[] mean, and when to choose a sibling. With no output schema to fall back on, this description carries the full burden and delivers.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds valuable context beyond the schema by explaining what depth levels actually do: quick=3 facets single hop, standard=5 with gap recovery + contradictions scan, thorough=8 paid with iterative hop. It also clarifies that broad multi-part questions are fine and decomposition is the point, adding meaning to the 'question' parameter. Only minor deduction for not fully elaborating the output structure, but that's not required.

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

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

The description opens with 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' and clearly distinguishes itself from open-web search. It names specific use cases ('compare X and Y's regulatory + financial exposure') and contrasts with sibling tools like ask_pipeworx, making its purpose unmistakable.

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

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

The description explicitly states when to use this tool vs alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' It also explains when deep_research is appropriate (broad/multi-part questions over structured data) and notes account requirements and depth tiers.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: it returns top-N relevant tools with full schemas and examples, ready to call directly, eliminating a second schema lookup. 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 concise and front-loaded: it states purpose, usage scenarios, and benefits in three sentences. 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 tool without an output schema, the description explains what is returned (tools with names, descriptions, schemas, examples) and why (ready to call). It covers input sufficiently and fits the complexity of a discovery tool.

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

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

Schema coverage is 100% with six parameters all described. The description adds value by mentioning aliases (q, task, description, search) and that the query is a natural language description, but this is already covered in the schema. Basic baseline 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 specific verbs like 'Find tools by describing the data or task' and 'browse, search, look up, or discover', and explicitly lists domains (SEC filings, FDA drugs, etc.). It clearly distinguishes from sibling tools by positioning itself as a meta-tool for discovery, instructing to call it FIRST.

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 states when to use ('when you need to browse, search, look up, or discover') and includes a directive ('Call this FIRST when you have many tools available'). It does not explicitly state when not to use, but the context is clear enough for a discovery tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds rich behavioral details: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; return structure (cik, filings with URIs, fundamentals sorted, patents soft-fail, news fallback); no contradiction. Adds significant context beyond annotations.

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

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

Single dense paragraph, but efficiently packs purpose, examples, usage guidance, behavioral details, and parameter specifics. No wasted words. Slightly long but justified by information density.

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 complexity (multiple sources, soft-fail, fallback), schema covers params fully, no output schema but description explicitly lists return fields (cik, filings, fundamentals, patents, news, LEI). Agent has complete understanding of inputs and outputs.

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 100%, baseline 3. Description adds critical context: type enum only 'company' supported, value must be ticker or zero-padded CIK, names not supported. These clarifications go beyond schema descriptions and help agent avoid mistakes.

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

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

Description provides specific verb+resource: 'full cross-source profile of a US public company'. Includes example queries ('Tell me about X', 'research Acme') and distinguishes from sibling resolve_entity by noting 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?

Explicitly states when to use ('ALWAYS PREFER over chaining single-pack ... when user asks for a holistic view') and when not ('names not supported – use resolve_entity first'). Clear guidance on 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds that it deletes by key and mentions use cases for clearing sensitive data, providing context beyond annotations. It does not contradict annotations.

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

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

The description is two sentences, front-loaded with the main purpose. Every sentence adds value: the first states the action, the second gives usage conditions and related tools. No wasted words.

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

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

The tool is simple with one parameter, annotations provided, and no output schema. The description covers the action, usage scenarios, and related tools. It is complete for this simple tool.

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

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

Schema coverage is 100%, and the schema provides a description for the 'key' parameter. The tool description does not add additional parameter details beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key.' The verb 'delete' and resource 'memory' are specific. It mentions pairing with 'remember' and 'recall' but does not explicitly differentiate from these siblings; however, the purpose 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 contexts: 'when context is stale, the task is done, or you want to clear sensitive data.' It suggests pairing with remember and recall, offering clear guidance. However, it does not specify when not 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 indicate readOnly, idempotent, non-destructive. The description adds behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond annotations by describing the extraction process and output format. 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 three sentences long, front-loaded with purpose, followed by process, then use cases. Every sentence adds value; no redundancy or filler.

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

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

Despite no output schema, the description fully explains the output format ('standard llms.txt markdown format', 'single text blob ready to drop at site-root/llms.txt'). Combined with annotations and schema, it provides complete context for successful 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% with clear descriptions for both parameters (url and max_links). The description does not add additional meaning beyond what the schema provides, other than implying the output format context. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Generate') and clearly identifies the resource ('llms.txt file') and domain ('for any URL so AI crawlers can index the site cleanly'). It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on generating the specific file format.

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

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

The description explicitly lists three concrete use cases: getting a client's site indexed, drafting for your own project, or auditing a competitor. It does not mention when to avoid using it or compare to alternatives, 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 indicate read-only, idempotent, non-destructive behavior. Description adds that it returns specific fields and defaults to active subscriptions, complementing the annotations without redundancy.

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 with no unnecessary words; first sentence defines behavior and output, second sentence specifies use cases. Exceptionally concise.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, output fields, and usage context adequately. No apparent gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions 'active' but does not elaborate on the include_inactive parameter beyond what the schema provides.

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

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

The description clearly states it lists the caller's active subscriptions and enumerates the returned fields. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing.

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 advises using this tool to review monitored subscriptions before adding more or to find an id to cancel, providing clear context for when it should be used.

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 annotations are all false and offer no safety clues, so the description carries full weight. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), and internal handling ('The team reads digests daily and signal directly affects roadmap'). It also warns about the cost of misuse ('reporting it here only delays you'). This exceeds typical behavioral disclosure for a feedback tool.

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

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

The description is longer than average but every sentence adds critical context: scope restriction, formatting guidance, rate limits, and quota implications. The first sentence states the purpose, followed by logical sections for when to use, what to avoid, and practical details. No filler or repetition of schema fields.

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 (3 params, no output schema), the description fully covers what an agent needs: when to submit, what to submit, what not to submit, rate limits, and the fact that it's free. It even addresses edge cases like not knowing whether a tool is Pipeworx's. There is no missing behavioral or contextual information.

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

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

The schema already documents all parameters at 100% coverage, so the baseline is 3. The description adds meaningful guidance on how to write the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.') and implicitly maps type values to scenarios. This extra context goes beyond the schema without being redundant.

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

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

The description starts with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates distinct use cases (bug, feature/data_gap, praise) and is clearly differentiated from sibling research tools like ask_pipeworx or deep_research.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and explains what to do for other servers, with a troubleshooting hint about identifying Pipeworx tools.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' No contradictions with annotations.

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

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

The description is two sentences plus a bullet list. It is front-loaded with the main action, and every sentence adds meaningful information without redundancy. Very concise yet comprehensive.

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, no output schema), the description is complete: it explains the return content, caching behavior, data source, and use cases. No gaps remain.

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

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

Schema coverage is 100% with a single parameter 'window' having an enum and description. The description adds value by explaining the trade-offs: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

The description clearly states what the tool does: returns top tools, top packs, and total call volume over a recent window. It uses specific verbs ('Returns') and resources, and the purpose is distinct from sibling tools like 'discover_tools' or 'ask_pipeworx'.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use cases). It provides context but does not explicitly state when not to use or alternatives, though the tool's uniqueness makes alternatives less relevant.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds extensive behavioral details beyond annotations: how monotonicity violations and partition checks work, semantic anchor using Jaccard similarity, partition filter on placeholder slugs, fill check against CLOB depth, and realizable edge calculation. No contradictions.

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

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

The description is dense but well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It packs many details without redundancy, though it could be slightly more concise. Every sentence adds necessary context for using the tool correctly.

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

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

With no output schema, the description fully explains the response format (opportunities[] with fields, partition_check details) and critical nuances like fill check logic. It covers edge cases (placeholder filtering, low similarity skipping) and links to a sibling tool for custom sizing. The tool's complexity demands this level of detail.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining each parameter's mode: 'event' is a Polymarket event slug that walks child markets, 'topic' is a seed question for cross-event scanning. It provides examples like 'fed-decision-may-2026' and explains behaviors unique to each. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) with specific use cases, e.g., 'pass event for the strongest per-event partition_check' and 'topic for a themed cross-event scan.' This provides a specific verb+resource and differentiates from siblings.

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

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

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...' It recommends event mode for specific markets and explains cross-event mode catches patterns single-event misses. It also advises when not to trade via fill check: 'do not trade it' if realizable_edge_pp ≤ 0.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extensive behavioral context: caching ('Cached 1h'), response structure with segments and diagnostics, edge calculation details, and limitations like Fed bets excluded. This goes well beyond the annotations, making the tool's behavior fully transparent.

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 comprehensive but verbose (over 400 words). It is well-structured with clear sections (model families, knobs, response top-level), but contains technical details (e.g., per-sport alpha values) that may not be necessary for understanding the tool's purpose. Not every sentence earns its place, reducing conciseness.

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 complexity (9 parameters, no output schema, complex internal logic), the description covers critical aspects: response structure with diagnostics, caching, edge calculation details, filtering reasons. It explains why segments might be empty and provides guidance on knobs. Minor omission: no mention of rate limits or authentication, but annotations already imply safe usage.

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 baseline is 3. The description adds some extra context for parameters (e.g., min_kelly explains why to use it; min_partition_leg_kelly explains relationship with basket trades). But the added value over the already-rich schema descriptions is marginal, as the schema already covers the meaning and usage of each parameter.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan', 'return') and resource ('Polymarket markets'), and distinguishes itself from sibling tools like 'polymarket_arbitrage' and 'polymarket_edge_tracker' by focusing on Pipeworx disagreement.

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 the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains the filtering knobs and diagnostics for understanding empty segments, guiding usage. However, it does not explicitly mention when not to use this tool versus alternatives, though the detail on limitations (e.g., Fed bets excluded) implies when to avoid relying on it.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: history bounded by 60-day TTL, decay computed from daily closes, and explanation of why snapshots may have gaps. This goes beyond the annotations.

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

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

The description is front-loaded with the core purpose, then details outputs and limitations in a structured way. It is somewhat verbose but each sentence adds value; could be slightly tighter but overall well-organized.

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 comprehensively explains all return fields (tracked with time-series, expired, snapshot_dates) and covers limitations (TTL, gap reasons). This fully compensates for the missing output schema.

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

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

Schema coverage is 100% with good parameter descriptions. The description restates defaults and options (e.g., window values) but does not add new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis, and specifies output fields (tracked, expired, snapshot_dates).

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

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

The description implies usage context: it helps assess whether an edge is fresh or old, which is crucial for trade decisions. It does not explicitly list alternatives or when not to use, but the purpose is clear and guidance is implicit.

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

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

Annotations already indicate read-only, idempotent, non-destructive, and open-world behavior. The description goes beyond by explaining that it walks the order book ladder, returns specific fields (e.g., slippage, verdict, forced_directional_risk), and warns about the dangers of partial basket fills. This adds valuable risk context without contradicting annotations.

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

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

The description is lengthy but well-structured: it starts with the core purpose, then covers mode requirements, single-market details, basket details, and ends with usage recommendations. Each sentence adds value, though some redundancy (e.g., repeating default values) could be trimmed. Overall, it is appropriately detailed for a complex 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?

Given the tool's complexity (two modes, no output schema), the description fully explains return values for both modes, including edge cases like thin_legs, max_clean_notional_usd, and forced_directional_risk. It also covers input constraints (e.g., size_usd clamp). No critical information is missing.

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

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

Schema description coverage is 100%, and the description adds substantial extra meaning: it explains the two modes (market vs event), default values, interpretation of size_usd (max spend vs target proceeds), auto-detection of side for basket mode, and the clamping range. This goes well beyond the schema's basic property descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two distinct modes (single-market and basket) and lists the returned fields, making it completely unambiguous. It also distinguishes itself from sibling tools by explicitly recommending use before acting on polymarket_arbitrage or polymarket_edges signals.

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

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

The description provides explicit guidance on when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the rationale (overround not capturable on thin books, partial fills converting arb to directional risk), giving clear context for decision-making.

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

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

Despite annotations declaring readOnlyHint, idempotentHint, etc., the description adds extensive behavioral context: compatibility_warning conditions, temporal_alignment, skipped_cross counters, and real spread rarity. 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?

Description is long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value; could be slightly condensed but effective.

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 response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, counters). Covers all inputs, warnings, and edge cases, making it self-contained.

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

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

Schema coverage is 100% with descriptions already present. Description adds value by explaining topic as pre-mapped shortcuts, explicit overrides, and providing examples. Does not contradict or redundantly restate 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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It uses specific verbs like 'cross-venue spread' and distinguishes from sibling tools (none other do this).

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 describes two usage modes (topic shortcuts or explicit tickers) and warns that pre-mapped topics often return compatibility_warning. Implicitly states when to use (comparing same outcome across venues) but lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. Description adds behavioral context: 'recent' time frame, amount ranges, and disclosure dates, which supplements the annotations.

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

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

Two sentences plus a clear example. Every part is essential: purpose, usage, and parameter behavior. No redundancy, efficiently front-loaded.

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

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

For a tool with only two parameters and no output schema, the description fully covers purpose, usage, parameter semantics, and includes an example. Nothing essential is missing.

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 parameters. The description adds value by explaining when to use the ticker parameter vs omit, and provides pricing/source info for the API key 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?

Description clearly states the tool returns 'Recent US Congress stock trades' with details on who, what, amount ranges, and disclosure dates. It also differentiates from sibling Quiver tools (contracts, insiders, lobbying) by specifying the domain.

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 guidance: pass a ticker for company-specific history or omit for the latest cross-market feed. Includes an example and notes the required API key. Does not explicitly list exclusions but context is sufficient given sibling tool variety.

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 that it returns award amount, agency, and date for US federal contracts, providing behavioral context beyond the annotations.

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

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

Two short sentences that front-load the purpose and include an example. No wasted words.

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

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

For a simple tool with two parameters and no output schema, the description covers purpose, parameters, and usage completely.

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

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

Schema coverage is 100%, and the description adds usage examples and clarifies that ticker is optional, which supplements the schema's 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 it retrieves US federal government contracts for a given ticker, specifying the data fields (award amount, agency, date). It differentiates from sibling Quiver tools like quiver_congress_trading or quiver_insiders by focusing on government contracts.

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

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

The description gives a clear example of usage and explains that omitting the ticker returns the latest cross-market feed. It does not explicitly state when not to use or name alternative tools, but the context is sufficient for an agent.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds value by specifying the exact output fields (insider name, share count, date) and providing an example, which gives the agent additional context beyond annotations.

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

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

The description is two sentences plus an example, with the purpose front-loaded. Every sentence is essential and there is 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 tool with only two parameters and no output schema, the description is complete. It explains what data is returned (insider name, share count, date) and includes an example, making it sufficient 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 with full descriptions. The description's example usage adds practical context showing the required format for both ticker and _apiKey, which is valuable for an agent.

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

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

The description explicitly states it provides SEC insider (Form 4) transactions for a ticker, with specific fields like insider name, share count, and date. This clearly distinguishes it from sibling tools like quiver_congress_trading or quiver_gov_contracts.

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

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

The description clearly states the tool's purpose and provides an example, but it does not offer guidance on when to use it versus alternatives, nor does it specify when not to use it.

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

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

Annotations already declare safe read operation. Description adds the return fields (client, amount, date, issue), but doesn't elaborate on behavioral aspects like authentication or data freshness. Adequate given annotation coverage.

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?

Single sentence with example, no wasted words. Front-loaded with purpose and key details.

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

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

For a simple two-parameter lookup tool with comprehensive annotations, the description covers purpose and returned fields. Lacks output schema but is complete enough for an agent to use correctly.

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

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

Schema covers both parameters with descriptions. Description reiterates ticker usage in example but adds no new semantic detail beyond what schema already provides. Baseline 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?

Clearly states it retrieves corporate lobbying disclosures for a stock ticker, with specific fields (client, amount, date, issue). Distinguishes from sibling tools like quiver_congress_trading by focusing on lobbying spend.

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

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

No guidance on when to use this tool over alternatives (e.g., other quiver tools). Only provides an example but no context about selection or exclusion criteria.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping details (identifier-based) and listing behavior, enhancing 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?

Three sentences, front-loaded with main action, no wasted words. Could be slightly more concise by merging usage and scope, but good overall.

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 single optional parameter, no output schema, and annotations, the description covers usage, scope, and alternatives. No major gaps.

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

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

Schema coverage is 100%, and description reinforces the key parameter's optionality and listing behavior, but adds no new syntax details 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 retrieves a value by key or lists all keys when omitted, distinguishing it from siblings 'remember' and 'forget'.

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: 'look up context stored earlier' and mentions pairing with remember/forget, providing clear 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?

Description states 'Set mark_read:true to flag returned events read' which implies a state change, contradicting the annotation readOnlyHint=true. According to rules, score 1 for 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?

Five sentences with no wasted words. Well-structured: purpose, return fields, filtering, side effect, alternative access method.

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?

Most aspects covered: return fields, filtering, side effect, alternative endpoint. Not fully complete (e.g., no explanation of 'fired events' or limit parameter), but adequate for a read tool with high schema coverage.

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%. Description adds value by giving an example type ('sec_8k') and explaining the effect of mark_read, going beyond 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?

Clear verb 'Pull' and resource 'fired events from your subscription feed'. Distinguishes from sibling subscription management tools by focusing on retrieving alert events.

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 mentions polling is fine and provides alternative REST endpoint, giving clear usage context. Does not exclude other sibling tools but provides an alternative.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds significant behavioral details: fans out to three sources in parallel, fallback logic (GDELT→GNews), rate-limit handling, soft-fail for USPTO, and return format. 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?

Single paragraph of ~150 words, front-loaded with purpose and examples. Every sentence provides necessary information without redundancy. Efficiently covers multiple sources and edge cases.

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

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

Despite no output schema, the description specifies return structure (changes[] grouped by source, total_changes count, pipeworx:// URIs). Covers all three sources, window options, fallback, and distinguishes from entity_profile. Complete for a complex tool.

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

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

Schema coverage is 100% with good descriptions. The description adds value by explaining shorthand for 'since' and showing example usage ('7d', '30d'), clarifying that 'value' can be ticker or CIK, and noting only 'company' type supported.

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

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

The description clearly states the tool's purpose: change feed for a company in the last N days/weeks/months, with specific verb 'get changes' and resources (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes from sibling 'entity_profile' by advising when to use the alternative.

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

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

Provides explicit usage context with example queries ('What's new with X') and explicitly recommends entity_profile for static profiles. Does not cover all sibling alternatives but gives clear fallback behavior for GDELT→GNews.

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?

Description complements annotations by adding behavioral details: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. Annotations already indicate idempotency and non-destructiveness, so description adds useful 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?

Three sentences efficiently convey purpose, usage, and persistence details. Information is front-loaded: 'Save data the agent will need to reuse later.' No redundant words.

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

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

For a simple key-value store with 2 parameters and no output schema, the description covers purpose, usage scenarios, persistence behavior, and companion tools (recall, forget). No gaps remain for correct agent 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%, baseline 3. Description enhances parameter understanding by giving concrete key examples (subject_property, target_ticker) and value types (findings, addresses), adding meaning beyond the schema's generic 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 explicitly states the tool saves data for reuse across conversations, with concrete examples (resolved ticker, target address, etc.). It distinguishes from siblings (recall, forget) and uses specific verbs (save, store, reuse).

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

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

The description explains when to use ('when you discover something worth carrying forward') and provides examples of what to store. It also instructs pairing with recall and forget, offering clear guidance on alternatives.

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

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

Although annotations already declare read-only, idempotent, and non-destructive behavior, the description adds significant context: internal cascading through multiple endpoints, auto-disambiguation for companies, and citation URI outputs. This goes well beyond the annotations.

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

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

The description is relatively long but front-loaded with example queries and clearly organized by supported types. Every sentence provides useful information, though it could be slightly tightened without losing value.

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

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

For a two-parameter lookup tool with no output schema, the description fully covers input formats, return values, supported types, and even mention of internal behavior. An agent has everything needed to invoke this tool correctly.

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

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

Schema coverage is 100% with per-parameter descriptions, but the tool description adds meaningful detail: the type parameter is explained with what each returns, and the value parameter includes examples (AAPL, CIK format, brand names) and notes auto-disambiguation. This enriches 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 resolves user-spoken names to canonical identifiers, with explicit examples ('What's the ticker for…'), supported types (company, drug), and specific return values. It distinguishes itself from siblings by noting it should be used whenever you have a name but need an ID.

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

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

The description gives an explicit when-to-use instruction: 'Use FIRST whenever you have a name but need an ID.' It also notes it replaces 2-3 manual lookups, providing clear context. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations declare readOnly, idempotent, not destructive. Description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, returns score/confidence/signal density per entity. No contradictions.

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

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

Four efficient sentences: first states main purpose, second explains mechanism, third gives use case with quote, fourth describes output. 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?

Describes output format (ranked list with score, confidence, signal density) but does not explain all input parameters (models, _apiKey, context). No output schema provided, so more detail on output would help.

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 4 parameters with descriptions (100% coverage). Description does not add additional meaning beyond schema; it mentions entities and output but not models, _apiKey, or context.

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

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

Description clearly states it compares AI visibility across multiple entities using ai_visibility_check, ranks them, and returns a ranked list. It distinguishes from sibling ai_visibility_check by noting it probes multiple entities.

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

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

Explicitly states use case for competitive AI-marketing audits and gives an example. Does not explicitly state when not to use or alternatives, but context implies single-entity queries should use ai_visibility_check.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timed out sources. 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 somewhat lengthy but every sentence adds value. It is front-loaded with the core purpose and key details. Could be slightly more concise, but structure is logical and effective.

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 details the return structure (summary block, per-advisory detail, links, alternative versions) and explains error handling. This is highly complete for a complex composite tool.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds extra context: scoped packages like '@types/node' are accepted, and version defaults to latest when omitted. This goes beyond what schema provides.

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

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

The description clearly states the tool is a composite check for npm packages covering license, advisories, version history, and bundle size. It uses specific verbs like 'fans out across deps.dev and bundlephobia' and distinguishes from sibling tools like 'deep_research' or 'validate_claim'.

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 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also scopes to npm ecosystem in v1 and mentions where to find other ecosystems, providing clear context and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds valuable details: character offsets for verification, embedding model (BGE-base-en), chunking (500-char overlapping windows), input cap (200K chars with truncation flagging). No contradictions.

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

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

The description is concise (about 5 sentences) and front-loaded with the core purpose. Every sentence adds value: usage, pairing, implementation details, and constraints. 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?

Despite lacking an output schema, the description sufficiently covers return values ('top-N passages with character offsets and similarity scores') and edge cases (truncation flagging). The behavior is fully described for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples for 'query' (e.g., 'supply-chain risk'), clarifies 'text' max chars, and specifies 'limit' range and default (1-20, default 5). This enriches understanding beyond schema.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record.' It specifies the verb 'search', the resource 'text inside a record', and distinguishes itself from siblings by explaining when to use it (when record is too large) and how it pairs with ask_pipeworx_grounded.

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

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

The description gives explicit context for use: 'Use when the record is too big to cram into the prompt.' It also mentions pairing with ask_pipeworx_grounded. While it doesn't list alternatives or when-not-to-use explicitly, the guidance is clear and actionable.

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

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

The description discloses many behavioral details: account requirement, supported types with parameter examples, delivery channels with constraints (email, SMS with verification and cap, webhook with signing and auto-disable). Annotations already indicate readOnlyHint=false and destructiveHint=false, and the description adds rich context about what the tool does and its side effects.

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

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

The description is moderately long but every sentence adds value. It is well-structured, starting with the main purpose, then prerequisites, supported types, and delivery channels. Minor redundancy (e.g., repeating delivery constraints in the delivery object description) but overall 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 no output schema, the description covers the return value (subscription id) and explains the always-on feed and optional delivery behaviors. It addresses prerequisites, type-specific parameters, and channel limitations. The tool has moderate complexity, and the description provides sufficient context for an AI agent to use it correctly.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description adds significant extra meaning with concrete examples for each type (e.g., sec_8k items, polymarket_edge topic) and details on delivery constraints (phone verification, SMS cap, webhook auto-disable). This goes well beyond the schema descriptions.

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

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

The description explicitly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It also mentions the return value (subscription id) and distinguishes itself from siblings like 'unsubscribe' and 'list_subscriptions' by being the creation 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?

The description provides clear context on when to use the tool (e.g., to set up alerts for specific event streams) and includes prerequisites (Pipeworx OAuth account). However, it does not explicitly compare to alternatives or state when not to use it, though the tool's uniqueness among siblings makes this less critical.

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

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

Annotations already provide readOnly, openWorld, idempotent hints. Description adds that results are drawn from the live catalog and return structured example questions with tool shapes, covering output behavior 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?

Front-loaded with common user queries, followed by a clear explanation of output and usage. Every sentence serves a purpose; the length is appropriate for an onboarding 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?

Despite no output schema, the description fully explains the return structure (category-bucketed examples with tool and argument shapes). Combined with rich annotations and sibling context, it leaves no critical gaps.

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

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

Schema coverage is 100% with a basic description for 'topic'. The description enriches this by listing exact focus areas (finance, pharma, etc.) and explaining the effect of omitting or providing the parameter, adding significant value.

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

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

The description clearly states it returns category-bucketed example questions with exact tool and argument shapes, serving as the onboarding entry point. This distinguishes it from siblings like ask_pipeworx or discover_tools.

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

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

Explicitly instructs to use this tool first when the agent doesn't know Pipeworx's capabilities, and describes calling with no arguments for full spread or passing a topic to focus. Also mentions learning to call meta-tools, providing clear context.

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

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

Beyond the annotations (readOnlyHint, destructiveHint, idempotentHint), the description adds critical behavior: ownership enforcement (only own subscriptions) and the precise effect (deactivation, not deletion, with historical events preserved). This provides actionable context beyond what annotations convey.

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

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

Two sentences with no redundancy. The first sentence presents the action and primary constraint, the second adds a key behavioral detail. Every sentence earns its place.

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

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

For a simple one-parameter tool with annotations, the description covers purpose, constraints, and behavioral effects. It is nearly complete but lacks explicit mention of error scenarios (e.g., attempting to cancel another's subscription) or the return value, which are minor omissions given the low complexity.

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

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

The schema already describes the parameter 'id' as a UUID returned by subscribe, achieving 100% coverage. The description does not add new semantics to the parameter, so it meets the baseline of 3.

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

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

The description clearly states the action ('cancel') and the resource ('subscription by id'), and adds scoping constraints such as ownership enforcement and deactivation vs deletion. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by noting that the subscription is not permanently deleted and remains accessible via 'recent_alerts'.

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

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

The description implies the tool is for canceling a subscription you own, providing clear context for use. However, it does not explicitly state when not to use it or suggest alternative tools like 'subscribe' for creating subscriptions, though the distinction is implicit.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: the two execution paths, the use of exact percent-delta math for financials, fallback to grounded pipeline, and the output structure (verdict, value with citation, reasoning). 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 well-structured: it starts with example queries, then explains the two verification paths, and finally lists output fields. While somewhat verbose, every sentence adds value and is front-loaded with key information. No redundant content.

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

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

Given the tool's complexity (two pipelines, multiple output fields) and the lack of an output schema, the description fully covers the return type (verdict, actual value with citation, reasoning). It also explains internal routing and edge cases, making it self-sufficient for an agent to understand behavior.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning beyond the schema: it explains that claim is a natural-language factual claim with examples, and that tolerance_pct overrides the implied tolerance with specific guidance for hallucination detection. This enriches parameter understanding.

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

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

The description uses specific verbs like 'verify', 'fact check', 'confirm or refute' and clearly defines the resource as natural-language claim verification. It distinguishes itself from sibling tools by explaining its unique dual pipeline (SEC EDGAR for financials, grounded pipeline for other facts) and that it replaces multiple sequential calls.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and provides examples. It explains the internal routing logic, giving clear context for when each path is used, though it doesn't explicitly list when not to use or name sibling alternatives.

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