Quotable

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), description adds cost transparency (free default, BYO key for Anthropic), key handling, and return structure (per-model + combined view). No contradictions with annotations.

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

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

Two sentences, front-loaded with main action and output, followed by usage guidance and return structure. No unnecessary 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?

No output schema, but description fully covers return type (per-model {score, confidence, signals, raw_response} + combined view), all 4 parameters explained, and optional context usage. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context beyond schema: default model, BYO key usage, and context disambiguation role, justifying a 4.

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

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

The description clearly states the tool probes LLMs for visibility scores (0-100) per model, with specific verb (probe, score) and resource (business/brand/product/topic). It distinguishes from sibling Q&A tools like ask_pipeworx by focusing on visibility scoring rather than factual questions.

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 cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Provides default model and cost details. Does not explicitly list when to avoid, but sibling differentiation is clear from purpose.

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

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

Annotations already declare read-only, non-destructive behavior, and the description adds meaningful context: it routes to 5,529 tools, fills arguments, returns structured answers with stable citation URIs. This goes beyond annotations to explain internal mechanics and output format.

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, front-loaded with 'PREFER OVER WEB SEARCH' and followed by examples and escalation paths. While every sentence earns its place, it is more verbose than necessary; a slightly tighter version would merit a 5.

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

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

Given the tool's complexity as a router, the description covers purpose, usage, examples, alternatives, and return format (citation URIs) without an output schema. It is remarkably complete for a 6-parameter tool with no output schema.

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

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

Schema coverage is 100% with all six parameters clearly documented as aliases for 'question'. The description provides rich natural-language examples, but these don't add semantic meaning beyond what the schema already conveys; the baseline of 3 is appropriate.

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

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

The description clearly states it answers factual questions by routing to thousands of tools, with specific examples and entity types. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH'), specific trigger phrases ('what is', 'look up', 'find'), and names alternatives with step-up criteria (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). It also covers edge cases like breaking news.

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

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

Annotations already declare readOnly and idempotent, so the bar is lower. The description adds valuable context: it is an experimental edge with active candidate improvements, currently identical to stable, and is a full working router with no fallback. This clarifies behavioral risk beyond the annotations, though it doesn't detail potential failure modes or specific routing behavior variations.

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

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

The description is compact but contains some redundancy, repeating 'same' multiple times. It is front-loaded with the key 'Beta version' context and structured with clear sentences, but a slightly tighter phrasing could improve clarity without losing information.

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

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

Given no output schema and a complex router tool, the description covers the key contextual points: beta status, current equivalence to ask_pipeworx, active improvement lifecycle, and comparison process. It doesn't explain the routing logic itself, but that is not expected for a beta wrapper since it behaves like the stable router when no candidate is active.

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

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

The schema has 100% coverage of six parameters with one required, so the baseline is 3. The description adds no parameter-specific detail but affirms 'same arguments' as ask_pipeworx, which is acceptable given the schema already fully documents the aliases and the natural language question 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 identifies the tool as a beta version of ask_pipeworx with an identical universal router (same 5,529 tools, same arguments, same response shape) and candidate routing improvements. This distinguishes it from the stable sibling ask_pipeworx and other tools by emphasizing its 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?

The description explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that it currently matches ask_pipeworx when no candidate is active, giving clear context for choosing this over the stable 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses concrete behavioral traits: it extracts answers using only tool results, returns verbatim evidence, and explicitly refuses with structured refusal_reason values when data doesn't directly answer. It also mentions the extra LLM call cost, which is relevant for agent planning. 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 information-dense but well-structured, with the core purpose front-loaded in the first sentence. It efficiently packs success/refusal formats, use cases, and cost trade-offs into coherent sentences. While not as terse as two-sentence examples, every clause earns its place and no content is redundant with annotations or schema.

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

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

The description is fully self-contained for agent selection and invocation: it explains the routing behavior, the output shape on success (including evidence, confidence, source) and all refusal reasons, plus when to prefer the cheaper sibling. Given the lack of an output schema, this is essential and complete.

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

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

The input schema already covers all parameters completely, with the 'question' parameter description explaining aliases and natural language input. The tool description does not add significant parameter-level semantics beyond what the schema provides, so it stays at the baseline of 3 for high schema coverage.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' which clearly states a specific verb+resource with a distinctive scope. It explicitly distinguishes from the sibling ask_pipeworx by emphasizing extraction-only answers and evidence, making the tool's unique purpose unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists example contexts (financial verdicts, legal claims, medical lookups, public statements). It also provides a clear when-not-to-use and alternative: 'prefer ask_pipeworx for casual lookups,' citing the extra LLM call cost.

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

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

The description goes far beyond the annotations. It details the fan-out process, response shapes, resolver contract with confidence levels, parent_event extraction, news fields with fallback, safety short-circuits, closed market handling, wide spread warnings, and cancellation rule parsing. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false).

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 approximately 700 words, very detailed but not concise. While front-loaded with core purpose, the abundance of examples, classifiers, and edge cases makes it lengthy. Could be more structured with subsections or bullet points.

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

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

Given the tool's complexity (multiple classifiers, fan-out, response shapes), the description is extremely complete. It covers all major aspects: low-confidence matches, closed markets, wide spreads, cancellation rules, and detailed response structure. No output schema exists, so the description carries the full burden and succeeds.

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 each parameter (market, depth, include_raw). The tool description adds overall context but not per-parameter additional meaning beyond examples. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and differentiates from siblings like polymarket_edges and polymarket_arbitrage by its comprehensive data gathering and analysis.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides examples of fan-out and how to interpret results. However, it does not mention when not to use it or compare directly to other 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses specific behavior: for company type it pulls latest 10-K data with correct fiscal year handling, for drug type it pulls FAERS counts, FDA approvals, and trial counts. It also states results are sorted by primary metric and includes citation 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 front-loaded with example queries and a clear command to prefer this tool. It provides pertinent details about data sources and sorting. While it is relatively long, every sentence serves a purpose and there is no extraneous information. Minor redundancy in listing example queries could be trimmed slightly.

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

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

Given the complexity of supporting two entity types with different data sources, the description covers all essential aspects: input constraints, data provenance, sorting behavior, and output format (paired data + URIs). There is no output schema, but the description adequately describes return values. The tool's purpose and usage are fully specified.

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

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

The input schema already provides descriptions for both parameters (type enum and values array). The description enriches this by explaining what each type returns (SEC data vs. FAERS data) and gives concrete examples of valid values (tickers/CIKs for companies, drug names). Schema coverage is 100%, so the description adds moderate extra value.

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

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

The description includes multiple example queries ('Compare X and Y', 'which is bigger', 'rank these companies') and explicitly states it performs side-by-side comparison of 2–5 companies or drugs. It clearly distinguishes from siblings like entity_profile by noting it replaces 8–15 sequential lookups.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool over alternatives. It also specifies the input patterns (e.g., tickers for companies, names for drugs) and the number of entities (2–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?

Discloses internal decomposition and parallel routing, return format (findings packet with gaps[]), citation guarantees, depth-specific behaviors (gap recovery, contradictions), and latency. Annotations already mark it safe; description adds context without contradiction.

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

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

The description is quite long but front-loaded with critical account and purpose information. Every sentence provides useful context, though it could be more structured. It's dense but not wasteful.

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

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

With no output schema, the description fully explains the return packet, including hop fields, citation URIs, contradictions, and gaps. It also covers timing and account requirements, making it sufficient for an agent to know what to expect.

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

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

Schema covers both parameters at 100%, so description only adds extra context like paid plan for thorough and expected latency. The depth parameter's meaning is largely in schema; description reinforces it.

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

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

The description clearly states the tool performs grounded multi-source research over Pipeworx's structured data sources, distinguishing it from open-web search and sibling tools like ask_pipeworx. It uses a specific verb and resource, and contrasts with alternatives.

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

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

Explicitly states when to use (broad/multi-part questions over structured data) and when to prefer ask_pipeworx (single lookup, current news). Also covers account/authentication prerequisites and alternative if not signed in.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed,' which expands on the response behavior 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 with no wasted words. The first sentence states the core purpose, and the second packs rich detail about return format and usage context without being verbose.

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 explains what is returned (tool names, descriptions, schemas with examples, ready to call) and lists example domains. It could mention pagination or error handling, but is sufficient for 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 descriptions for all 6 parameters. The description mentions query aliases ('task, q, description, search'), which is already documented in the schema. It adds no substantial new meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It also lists specific domains (SEC filings, FDA drugs, etc.), which distinguishes it from sibling tools that handle individual queries.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context, though it doesn't explicitly mention when not to use it or list alternatives beyond the implicit sibling set.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds significant behavioral context: it fans across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), notes a sunset for patents ('soft-fails until reactivated'), and describes fallback mechanisms. 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 informative but slightly lengthy. However, every sentence contributes value, with examples, explicit instructions, and a well-organized list of return components. It is front-loaded with usage guidance.

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

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

For a complex multi-source profile tool, the description is comprehensive. It explains the data sources, return fields, and limitations (e.g., patents sunset). Although no output schema exists, the description adequately describes return values. The openWorldHint justifies some openness.

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%, yet the description adds crucial meaning: examples of valid values ('AAPL', '0000320193'), clarification that names are not supported, and a pointer to resolve_entity. This goes beyond the schema's enum and 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 uses a specific verb-resource pair ('full cross-source profile of a US public company') and distinguishes itself from siblings by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'. It also provides example queries ('Tell me about X', 'brief me on Tesla') that clarify the scope.

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

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

The description explicitly states when to use: when the user asks for a holistic view of a company. It also specifies when not to use and how to proceed if only a name is provided ('use resolve_entity first'). It names an implicit alternative (chaining individual lookups) and gives a strong preference.

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 confirms destructive nature (delete) consistent with annotations (destructiveHint=true). No contradictions; does not add beyond annotations but aligns well.

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: first sentence states purpose, second provides usage guidelines. No wasted words, 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?

Simple tool with one parameter and annotations; description covers purpose, usage, and parameter. No output schema needed; complete for its 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?

Only one parameter 'key' with description 'Memory key to delete', which matches schema. Schema coverage 100%, so baseline 3 applies; no extra semantic detail added.

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 'Delete a previously stored memory by key', using a specific verb and resource. Distinguishes from sibling tools like 'remember' and 'recall'.

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 provides three use cases (stale context, task done, clear sensitive data) and recommends pairing with remember and recall.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate a safe, read-only, idempotent operation. The description adds process details: fetches the page, extracts title/description/links, and outputs markdown. 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 two sentences plus a bullet list, front-loading the core purpose and use cases. Every sentence adds value without redundancy or unnecessary detail.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers functionality, output format, and use cases. It clarifies the output as a text blob for deployment, compensating for the lack of 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%, and both parameters (url, max_links) are described in the schema with details. The description does not add new semantic meaning beyond what is already in the schema, so baseline 3 applies.

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

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

The description clearly states the tool's purpose: to generate a production-ready llms.txt file for any URL, enabling AI crawlers to index the site. It specifies the action, resource, and target audience, and distinguishes itself from sibling tools, none of which directly compete.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing a competitor. It guides when to use the tool but lacks explicit exclusions or alternatives, though siblings offer related but distinct functions.

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 already establish read-only, idempotent, and non-destructive characteristics. The description adds meaningful behavioral context: it returns 'bio, description, and total quote count,' and reveals that the list mode is unordered and cannot be searched—information not available from annotations alone.

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

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

The description is two sentences long, front-loaded with the primary action, and every phrase earns its place—covering the lookup mode, the fallback list mode, and the critical limitation without redundancy.

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

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

Given the presence of an output schema and full parameter descriptions, the description rounds out the context by explaining the two usage modes and the list's unordered nature. This is sufficient for a read-only lookup tool; no missing prerequisites or error scenarios are critical.

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 descriptions fully cover both parameters (slug with pipe-separated support, limit with range and rounding), so the description adds limited semantic detail. The only extra is the usage recommendation to prefer slug, which is more about context than parameter meaning. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Look up an author by slug' and specifies the resource (authors) and the key (slug). It also distinguishes the list mode and notes the limitation ('upstream list is unordered and cannot be searched'), differentiating it from search-focused siblings like search_quotes.

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 direct usage guidance by instructing users to 'prefer passing a slug' and explaining that the list mode is unordered and non-searchable. This implies when to use slug versus list, though it does not explicitly name alternative tools or exclusion 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by detailing return fields and the optional include_inactive parameter behavior, 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?

Two sentences, first states purpose, second gives usage guidance. 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?

Given simple input schema, no output schema, and comprehensive annotations, the description fully covers necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with a clear description for the single boolean parameter. The description does not add extra meaning beyond the schema.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It also lists the returned fields, distinguishing it from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly advises use for review before adding subscriptions or to find an id to cancel, providing clear context and alternative tool reference.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by specifying that tags are sorted by popularity, which is behavioral info not captured in annotations.

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

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

The description is two sentences with no filler. It front-loads the purpose and immediately gives actionable guidance.

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 zero parameters and rich annotations, the description fully covers what the agent needs to know. The output schema exists, so return value details are unnecessary.

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 tool has zero parameters, so baseline is 4. The description adds meaning beyond the schema by explaining the output (tags sorted by popularity) and its intended use.

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

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

The description clearly states the tool lists all available quote tags sorted by popularity, and explicitly connects its output to the random_quote tool. This distinguishes it from siblings like random_quote and search_quotes.

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 implicitly guides usage by stating when to retrieve tags and how to use them with random_quote. It does not explicitly state when not to use it or list alternatives, but the purpose is clear enough.

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 (which are all false, indicating the description carries the burden), it discloses that filing without an account returns a claim_token, how to later use that token to check status, the rate limit (5 per identifier per day), that it is free, and that it does not count against the tool-call quota. This is rich behavioral context with no contradiction to annotations.

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

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

Although the description is long, every sentence serves a purpose: purpose, use cases, exclusions, token mechanism, rate limit, and cost. It is front-loaded with the core purpose and then flows logically into guidelines and consequences. 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 description fully covers the tool's behavior for an agent: what it does, when to use, exclusions, token flow, rate limits, and expected team response. It is complete even without an output schema, and it stands out clearly among the sibling tools.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantic guidance: it scopes the feedback to tools served by this Pipeworx connection, instructs describing issues in terms of Pipeworx tools/packs, and explicitly says not to paste the end-user's prompt. These constraints are not fully captured in the schema and add real value.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from sibling tools by focusing on feedback submission rather than research or queries, and it enumerates the exact triggers (bug, feature/data_gap, praise).

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 scenarios (bug, feature/data_gap, praise) and a clear when-not-to-use exclusion: tools from a different MCP server. It also directs the user to file elsewhere for external server issues and gives practical instructions about what to include (Pipeworx tools/packs) and what to avoid (end-user prompt).

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive traits. Description adds valuable context: data derived from CF analytics-engine, no PII, caching 5min-1h. 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?

Concise, front-loaded with purpose, then use cases, then technical details. Every sentence adds value with no wasted words.

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

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

Covers purpose, usage, data source, privacy, caching. The only gap is the exact return structure (e.g., object fields), but the description states what is returned conceptually. Adequate for a 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?

The input schema already fully describes the single parameter with enum values and meaning. The main description adds no extra parameter guidance beyond mentioning windows exist. High schema coverage (100%) sets baseline at 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 the tool returns top tools, top packs, and total call volume over configurable windows. Distinguishes from siblings like discover_tools by focusing on trending usage.

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 three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases) and explains window choices (shorter for hot, longer for steady-state). No alternatives needed.

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?

Provides extensive behavioral details beyond annotations: monotonicity checks, partition-sum checks, semantic anchor Jaccard similarity, placeholder filter, fill check with theoretical vs realizable edge. It warns against unexecutable trades. Annotations (readOnly, openWorld, idempotent, non-destructive) are consistent with description.

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?

Well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) for readability. However, the description is quite lengthy; while justified by complexity, a slightly more concise presentation could improve efficiency.

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 thoroughly details the response structure (opportunities[], gap_pp, suggested_trade, reasoning, partition_check, fill_check). It covers edge cases and limitations, making it self-contained for a complex tool.

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

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

The description adds significant meaning beyond the input schema: explains event accepts slugs or URLs, topic is a seed question, and provides usage recommendations. Schema coverage is 100%, and the description 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 clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes three modes (trending scan, event-specific, cross-event) and differentiates from sibling tools by focusing on arbitrage detection methods.

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 for each mode: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. It explains when to use cross-event over single-event and directs to polymarket_fill_risk for custom sizing. It also advises not to trade when fill check shows zero realizable edge.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: five model families, response structure, caching, and diagnostics. It also notes that Fed candidates are excluded due to unreliable data, providing transparency 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 long but well-organized with sections and bullet points. Every sentence adds value, though it could be slightly more concise given the density of information.

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

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

Despite no output schema, the description thoroughly explains the response structure including segments, knobs, and diagnostics. It also covers caching and caveats about Fed data, making it complete for the complexity level.

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

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

Schema coverage is 100%, but the description adds significant value for each parameter, such as suggesting slippage adjustments for thin partitions and explaining why min_kelly does not filter partition arbs. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the resource (Polymarket markets) and the action (scanning returning opportunities), and the purpose is distinct from siblings like polymarket_arbitrage.

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

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

The description explicitly says it's built for 'what should I bet on today' and mentions that agents discover opportunities without paging hundreds of markets. However, it does not mention when not to use it or compare with alternatives among siblings, though the context is clear.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destructive action. The description adds extensive behavioral details: response structure (tracked, expired, snapshot_dates), that snapshots are written on cache-miss (gaps mean no scan), decay from daily closes, and history bounds. 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 front-loaded with purpose and includes all necessary details: args, response, limits. While somewhat dense, every sentence serves a purpose. Better structuring (e.g., bullet points for response) could improve, but it is efficient for the amount of information conveyed.

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

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

Given the tool's complexity, the absence of an output schema, and the richness of the input schema, the description fully explains what the tool does, its inputs, outputs, and constraints. It covers both the data returned and caveats like snapshot gaps and decay derivation.

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 context beyond schema names: for 'days' it explains lookback range and default, and for 'window' it explains snapshot family. This enriches the bare parameter descriptions.

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

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

The description states a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a concrete question: 'how long has this edge existed and is it shrinking?' This clearly distinguishes it from siblings like polymarket_edges (which likely provides current edges) and polymarket_arbitrage.

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 clear context for when to use the tool (e.g., distinguishing a fresh wide edge from an old one) and explains limits like the 60-day snapshot TTL. However, it does not explicitly state when not to use it or name alternatives like polymarket_edges for current data.

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

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

The description details behavioral traits beyond annotations: it explains the two modes, required parameters (one of market/event), return fields (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict), and warns about risks like thin legs and forced directional risk. This adds context that annotations (readOnlyHint, destructiveHint) do not cover.

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: a one-sentence summary, followed by clear sections for SINGLE-MARKET and BASKET modes with bold headings. Every sentence adds value, and it ends with a concise usage recommendation. No redundancy or 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?

Given the tool's complexity (two modes, no output schema), the description fully explains inputs, behavior, outputs, and risks for both modes. It lists all return fields, default values, constraints (size_usd clamp), and critical warnings. This covers all necessary context for an agent to use the tool correctly.

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

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

Although schema coverage is 100%, the description enriches parameter meaning: it explains size_usd differently for single-market vs basket ('max spend on buys, target proceeds on sells' vs 'settlement notional'), clarifies side defaults ('auto' for basket), and notes that one of market/event is required despite schema not marking them 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 clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by recommending its use before acting on their 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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills create directional risk).

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. The description goes further by detailing safety fields like compatibility_warning (explaining why spreads may be invalid), temporal_alignment, and skipped_cross_type/subtype counters. It also states when the tool says bet shapes aren't equivalent, providing full 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 relatively long but well-structured with clear sections (modes, response, safety fields). Every sentence adds necessary context, though it could be slightly more concise. No fluff, but the length is justified by the tool's complexity.

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

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

Given the tool's two modes, multiple safety checks, and complex response fields, the description covers all relevant aspects: mode selection, parameter overrides, response fields (legs, spreads, compatibility), and caveats about temporal misalignment. No output schema, but response fields are thoroughly described. Complete 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?

All 3 parameters have clear descriptions in the schema, but the description adds value by listing the 10 topic shortcuts and explaining override behavior. Input schema includes examples. Schema coverage is 100%, so the description complements effectively without redundancy.

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

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

The description clearly states it computes 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison. The verb 'compute spread' and specific market names make 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 describes two modes (topic shortcuts and custom tickers) with concrete examples. Warns that pre-mapped shortcuts often result in compatibility warnings, setting realistic expectations. Also explains when to use explicit mode ('for custom pairings') and notes that real spreads are rarer than the list suggests.

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

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

With annotations indicating read-only, idempotent, and non-destructive behavior, the description adds useful context: returns quote text, author, and tags, and tags come from a fixed list. This goes beyond annotations and clarifies the response shape and tag source. No contradiction found.

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 concise sentences that front-load the primary action, include filter examples, return contents, and a valuable tag-list tip. No redundant wording, 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?

Given the tool's simplicity, the description covers the core purpose, optional filters, return contents, and the tag prerequisite. An output schema exists, so return details are not required. It could mention the default limit or the random nature per call, but the description is already sufficient for most use cases.

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

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

The input schema already provides 100% coverage with descriptions for all three parameters. The description's mention of 'tag' and 'author slug' aligns with the schema but adds no new semantics. The fixed-list note is also present in the schema, so the description contributes minimal additional parameter meaning.

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

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

The description clearly states the tool's function: 'Get a random quote' with optional filters by tag or author slug. It also mentions return contents (quote text, author, tags), making the purpose explicit. It doesn't explicitly differentiate from sibling search_quotes, but the random nature is clear.

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

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

The description gives clear usage context: use when you want a random quote, optionally filtered. It also provides a direct pointer to list_tags as a prerequisite for tags, which is helpful. However, it doesn't explicitly mention when not to use this tool or alternatives like search_quotes, so it's not a full 5.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: scoping ('Scoped to your identifier...'), behavior when key omitted (list all), and pairing with remember/forget. 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 compact and well-structured: first sentence states the main action, then elaborates on when to use, scoping, and sibling pairing. Every sentence adds value with no wasted words.

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

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

Given no output schema, the description adequately explains what is returned (a value or list of keys) and mentions scoping. For a read-only retrieval tool with clear annotations, this is complete.

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

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

Schema coverage is 100% and already describes the parameter clearly ('Memory key to retrieve (omit to list all keys)'). The description reinforces this but adds only minimal extra semantics beyond pairing with siblings. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the verb (retrieve/list) and resource (saved values/keys), and distinguishes from sibling tools 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?

The description explicitly says when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It implies when not to use (use remember or forget) and names those sibling tools directly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the return fields (source, citation_uri, raw payload) and the behavior of mark_read (flags returned events as read), which is beyond what annotations provide. 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, with no wasted words. It front-loads the primary purpose, then details parameters and usage. Each sentence contributes meaningfully, achieving high density of information without verbosity.

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

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

Despite no output schema, the description explicitly states what each alert carries. It covers all parameters, usage patterns, and even an alternative API. For a read-only, idempotent tool with comprehensive annotations, this description is fully adequate.

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 meaning by clarifying that 'type' filters by subscription type, 'since' is an ISO timestamp, and 'mark_read' flags events as read. This goes beyond repeating schema definitions, providing actionable context.

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

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

The description clearly states it pulls fired events from the subscription feed and returns the most recent alerts. It specifies the resource (alerts) and the action (pull/return), distinguishing it from sibling tools by focusing on alert retrieval. The verb 'Pull' and resource 'fired events' are specific and unambiguous.

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

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

The description provides explicit guidance on filtering by type and since, using mark_read, and notes that polling works fine. It also mentions an alternative endpoint for scripts/dashboards. While it doesn't explicitly state when not to use this tool, the context is sufficient for an AI 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 declare readOnly, openWorld, idempotent hints. Description adds transparency about fan-out to multiple sources, fallback on rate limits, and soft-failure for USPTO. Describes return structure with groups and citation URIs.

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 a single paragraph but well-structured with example queries first, then technical details. Every sentence adds value. Could be slightly more concise but still efficient.

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

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

For a multi-source, fallback, date-parsing tool without output schema, the description is thorough. Explains sources, fallback, date formats, soft-failure, and return structure. No gaps observed.

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%, baseline 3. Description adds valuable context: explains 'since' accepts ISO or relative shorthand and that 'value' accepts ticker or CIK. Enhances 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?

Description clearly states it provides a change feed for a company (SEC, news, patents) in a given window. Uses specific verbs and example queries. Distinguishes from sibling tool 'entity_profile' via explicit usage guidance.

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

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

Explicitly states when to use this tool versus 'entity_profile' (static profile). Explains fallback mechanism (GDELT→GNews) and provides guidance on 'since' parameter formats (ISO or relative).

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

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

Discloses persistence behavior beyond annotations: authenticated users get persistent memory, anonymous sessions retain for 24 hours. Also implies overwriting (idempotent). 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?

Five sentences, front-loaded with purpose, then usage guidance, then behavioral detail. No redundancy or filler. Every sentence adds value.

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

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

Given rich annotations and schema, description fully covers purpose, usage, and behavioral traits. No missing information needed for tool selection or 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 inline descriptions for key and value. Description adds context by stating 'stored as a key-value pair' and providing examples, which reinforces parameter roles 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?

Description clearly states 'Save data the agent will need to reuse later' with specific verb (save), resource (memory), and context (across sessions). Distinguishes from siblings recall and forget by mentioning them explicitly.

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: 'when you discover something worth carrying forward' with concrete examples (ticker, address, preference). Also advises pairing with recall/forget for retrieval/deletion.

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

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

Beyond the readOnly/idempotent annotations, the description discloses valuable behavioral details: identifiers are labelled with their source, unresolved identifiers are explicitly listed under `unresolved` rather than omitted, and LEI/FIGI enrichment degrades gracefully if GLEIF or OpenFIGI is unavailable. It also reveals the internal cascading through multiple endpoints.

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 examples and a clear purpose, but it is somewhat lengthy. However, the detailed explanations of supported types and graceful degradation are relevant and justify the length; no sentence is purely redundant.

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

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

With no output schema, the description carries the burden of explaining return values. It covers the fields for company (CIK, ticker, company_name, LEI, FIGI), for drug (RxCUI, ingredient, brand), and the unresolved field and degradation behavior. It stops short of specifying the exact JSON structure, but it is sufficient for a complex tool with two modes.

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

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

The input schema already provides 100% coverage for both parameters, including the `type` enum and the accepted formats for `value`. The description reinforces these details but does not add new parameter-level semantics beyond what the schema states, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('resolve') and resource (user-spoken names to canonical/official identifiers), with multiple concrete examples of user queries. It distinguishes the tool's role by stating 'Use FIRST whenever you have a name but need an ID,' clearly separating it from sibling tools that operate on resolved IDs.

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: use when you have a name but need an ID, and it notes the tool replaces 2-3 manual lookups. It does not name specific sibling alternatives or exclusions, but the directive 'Use FIRST' is clear enough to guide selection.

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

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

Annotations declare readOnly, idempotent, and non-destructive. The description adds that it internally calls ai_visibility_check, requires an _apiKey for certain models, and returns a ranked list with score, confidence, signal density. 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 three sentences, front-loads the purpose, and contains no fluff. Every sentence adds value.

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

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

Given the complexity of comparing multiple entities and calling another tool, the description covers purpose, input behavior, and output structure. No output schema exists, but the description adequately specifies return fields. The entity limit (2-8) is in the schema.

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

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

Schema coverage is 100% with descriptions. The description adds extra meaning: the first entity is treated as 'subject' for narrative, which is not in the schema. This provides valuable guidance for usage.

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 compares AI visibility across multiple entities side-by-side, probing each with ai_visibility_check and ranking results. It differentiates from the sibling ai_visibility_check (single entity) and describes output, making purpose unambiguous.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and example question. However, it does not explicitly tell when not to use the tool or mention alternatives like ai_visibility_check for single entities, though this is implied through context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds crucial behavioral details: it fans out to two services (deps.dev and bundlephobia), notes that bundlephobia's first measurement can take 5-30 seconds, and explains partial failures degrade gracefully with a sources_failed list. 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 informative but somewhat lengthy. However, it is front-loaded with the core purpose and each sentence adds value. Minor improvement would be to shorten the list of return fields, but overall it maintains good structure.

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

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

Given the complexity of the tool (composite check, two services, multiple return fields) and no output schema, the description is remarkably thorough. It lists all return fields in parentheses, explains failure behavior, and mentions version history and links. The agent can fully understand inputs, outputs, and edge cases.

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 both parameters described. The description adds value beyond the schema: it clarifies that scoped packages (e.g., '@types/node') are accepted for the 'package' parameter, and that 'version' defaults to the latest published version. This enhances semantic 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 clearly states the tool's purpose as a composite check for npm packages covering license, advisories, version history, and bundle size. It specifies the exact use case ('should I add this npm package') and distinguishes from alternatives by noting ecosystem limitations and mentioning deps.dev:version for other package managers.

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 provides usage guidance: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'.' It also includes when not to use (other ecosystems) and directs to alternative tools, which is exemplary for an AI agent's 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no additional behavioral context such as rate limits, permission requirements, or search quirks; it merely restates the return of matching quotes, which is already implied by the tool's purpose.

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

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

The description is exactly two sentences, front-loaded with the action 'Search quotes by keyword or phrase,' and contains no redundant or superfluous words. It is efficiently structured and immediately informative.

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

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

For a simple search tool with a well-documented schema and annotations, the description is minimally adequate but lacks any usage context or mention of pagination or the limit's rounding behavior. The output schema likely covers return values, but the description could still note when to choose this tool over alternatives.

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 both 'query' and 'limit' described in detail, including the bucketing behavior for limit. The description's 'keyword or phrase' adds no additional meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Search quotes by keyword or phrase' with a specific verb and resource. It also specifies what is returned ('matching quotes with author names and topic tags'), distinguishing it from siblings like random_quote and get_authors.

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 no guidance on when to use this tool versus alternatives. It only states the operation without any exclusions, prerequisites, or named alternatives such as random_quote or search_within.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds significant behavioral details beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), character limit (200K chars with truncation flag). 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?

Single paragraph is well-structured: purpose first, then usage guidance, then technical details. Every sentence adds value without redundancy. 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?

Despite lacking an output schema, the description explains return values (top-N passages with character offsets and similarity scores). It also provides technical details (embedding, chunking, limit) that are essential for correct usage. The description is complete for a search-within-text tool.

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

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

Schema description coverage is 100% (all three parameters have descriptions). The description adds helpful examples for the query parameter and clarifies the default for limit (5). It also reiterates the max character limit for text. This adds some value beyond the schema, justifying a 4 above the baseline of 3.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific verbs ('search inside') and resources ('fetched record'). It distinguishes from siblings by contrasting with ask_pipeworx_grounded and implying it is not for fetching data but for searching within already-fetched text.

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: 'when the record is too big to cram into the prompt'. It also explains the benefits (saves context, returns only relevant passages) and mentions a complementary tool (ask_pipeworx_grounded) for grounding over passages.

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

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

Annotations provide readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description adds critical details: return value, always-on feed, optional channels, rate limits, and verification requirements. 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 well-organized and front-loaded, but slightly verbose with minor redundancy (e.g., repeating delivery details). Overall, each sentence adds value.

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

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

Given the tool's complexity (multiple types, delivery channels, authentication), the description covers all necessary context: return value, prerequisites, type parameters, and delivery constraints. No output schema but return stated.

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

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

Schema coverage is 100%, but the description enriches parameter understanding with type-specific examples, delivery channel constraints, and prerequisites. This significantly aids correct invocation beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a subscription ID. It effectively distinguishes from sibling tools like list_subscriptions and unsubscribe, which handle different operations.

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?

Prerequisites (Pipeworx OAuth account) are explicitly stated, and supported types with delivery channels are detailed. However, it lacks explicit 'when not to use' guidance, though context implies alternatives like listing or unsubscribing.

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, open-world, idempotent, and non-destructive. The description adds that it returns 'category-bucketed example questions (company financials, drugs & clinical trials, etc.) — each with the exact tool + argument shape that answers it, drawn from the live catalog of thousands of tools.' This provides detailed behavioral 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 slightly long but front-loaded with natural language queries, then clearly explains the tool's function and output. Each sentence adds value, though a minor trim could improve conciseness without losing 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 no output schema, the description fully explains what the tool returns (categorized example questions with tool calls) and mentions its role in learning meta-tools. It covers all necessary context for an onboarding/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 one parameter (topic) described. The description adds example values (finance, pharma, etc.) and clarifies that omitting the parameter gives a cross-category spread, enhancing the schema's meaning.

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

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

The description starts with common user queries and clearly states it is the onboarding entry point that returns category-bucketed example questions. It distinguishes itself from siblings like ask_pipeworx and entity_profile by specifying its role in helping users discover capabilities and tool usage.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides strong when-to-use guidance. It also mentions optional topic filtering but does not explicitly state when not to use it or list alternatives, though the context is clear.

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

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

Adds ownership enforcement and deactivation behavior beyond annotations. Aligns with idempotentHint and destructiveHint. 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 sentences, each essential: purpose and behavioral constraints. 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?

Fully addresses purpose, preconditions (ownership), side effects (deactivation, history), and ties to sibling recent_alerts. Adequate for a single-param 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?

Description repeats schema's parameter description but adds no new semantic context. Full schema coverage justifies 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?

Explicit verb 'Cancel' with resource 'subscription by id'. Distinguishes from siblings like subscribe (creates) and list_subscriptions (lists).

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

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

Clearly states ownership enforcement and that cancellation is deactivation not deletion, with direction to recent_alerts for history. Could be stronger with explicit when-not-to-use but suffices.

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 critical behavioral nuances: the semantics of each verdict (especially could_not_verify vs unsupported), the two distinct processing paths (SEC EDGAR for financial claims, grounded pipeline for others), and the caveat that could_not_verify must not be used as evidence. This aligns with and enriches the openWorldHint annotation.

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

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

The description is lengthy but well-structured: it opens with trigger phrases, states purpose, gives usage, explains the pipeline, lists verdicts, highlights a critical caveat, and closes with an efficiency claim. Every sentence contributes, though a bit verbose; it earns a 4 rather than 5 due to the length, but there is no fluff.

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

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

With no output schema, the description fully compensates by enumerating the verdict types, the inclusion of citations and reasoning, and explaining error states. It also covers both claim categories, tolerance behavior, and the tool's advantage over sequential calls. This is a complete and self-sufficient description 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%, so the baseline is 3. The description reiterates the tolerance_pct override and provides examples of the claim parameter, but it does not add new parameter-specific semantics beyond what the schema already states. It is adequate but not enhanced.

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

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

The description clearly identifies the tool as a natural-language claim verification tool against authoritative sources, with specific examples of user intents. It distinguishes itself from sibling tools by explicitly framing it as fact-checking, and even mentions replacing 4–6 sequential calls, which sets it apart from generic research or ask 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?

Provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also outlines the two routing paths for different claim types. However, it does not explicitly list when-not-to-use or name alternative sibling tools, so it misses the full 'alternatives' criterion for a 5.

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