Semanticscholar

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: that the tool queries LLMs, returns per-model scores and a combined view, and that Anthropic calls require a user-provided API key billed directly by Anthropic. 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 compact (3 sentences), front-loads the main action and purpose, then provides details on models and return format, and ends with use cases. Every sentence is informative and 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?

Given the tool's moderate complexity (4 params, no output schema), the description adequately covers input semantics, behavior, and return structure (per-model fields + combined view). It does not detail error handling or rate limits, but annotations and schema descriptions are sufficient for an agent.

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

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

All 4 parameters have descriptions in the schema (100% coverage). The description enriches understanding by explaining the default model, the role of `_apiKey` for Anthropic, and the purpose of `context` for disambiguation, adding value beyond the schema alone.

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 ('probe') and resource ('LLMs for what they know about a business / brand / product / topic'), clearly distinguishing the tool's unique function of scoring visibility from sibling tools that perform other tasks like asking questions or deep research.

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

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

The description specifies when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), explains default vs. paid model usage, and notes the optional `_apiKey` for Anthropic. It does not explicitly list alternative tools for similar tasks, but the context 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?

Annotations already cover read-only, open-world, idempotent, and non-destructive constraints. The description adds valuable behavioral context: it routes to 5,462 tools, fills arguments, returns structured answers with citation URIs, works on every tier, and is a single fast call. This goes beyond annotations without contradicting them.

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

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

The description is long but well-structured, with bolded directives and examples. It is front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and each sentence serves a purpose, though it could be tightened slightly to improve conciseness.

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

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

Given the tool's complexity (routing across thousands of sources) and the absence of an output schema, the description is remarkably complete. It covers what it returns (structured answer with citation URIs), when to use it, alternatives for different needs, and provides examples. This leaves little ambiguity for the agent.

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

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

The input schema has 100% coverage with descriptions for the main parameter and aliases. The description supplements this with concrete examples of acceptable questions and clarifies the natural-language nature of the input. This enriches the schema's meaning, justifying a score above the baseline.

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

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

The description clearly defines the tool as a query router that answers factual questions from a vast array of authoritative sources, with specific examples. 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 is explicit about when to use the tool: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It also provides clear alternatives: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, along with examples of triggering phrases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable context about its beta nature, that candidate routing improvements may be active, and that no candidate is currently active, so behavior matches ask_pipeworx. It also confirms it is a full working router with no fallback, which is useful beyond the annotations.

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

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

The description is three sentences, each earning its place. It front-loads the key beta distinction, then the current state, then usage instruction. No fluff or repetition, though it is dense with 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, the description adequately covers the essential context: beta status, current equivalence to ask_pipeworx, usage guidance, and reassurance that it is a full working router. It also notes the comparison against the stable router, which explains the purpose. No significant gaps.

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

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

Schema description coverage is 100%, with all six parameters (question and five aliases) documented. The description adds the note 'same arguments' as ask_pipeworx, which confirms compatibility but does not add new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the sibling ask_pipeworx by being the experimental edge, and explicitly notes it currently matches ask_pipeworx exactly.

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

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

The description explicitly tells the agent when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that results are compared against the stable router, implying the stable version is for non-beta use. This is clear guidance versus the primary alternative.

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

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

Annotations already provide readOnlyHint and idempotentHint, but the description adds substantial behavioral context: the return contract ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}), explicit refusal reasons, and the fact that it only uses tool-result content. It also notes the extra LLM call cost, all beyond annotation coverage and 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 front-loaded with the core purpose, then proceeds logically through behavior, return format, usage, and cost. It's somewhat lengthy but every sentence contributes meaningful information. The refusal-reason list is detailed but arguably necessary given no output schema.

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

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

With no output schema, the description fully compensates by specifying the exact success and failure return structures, including refusal reasons. It also covers routing, cost, and sibling differentiation, making it self-sufficient for an agent to understand the tool's complete behavior in context.

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

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

Schema coverage is 100% with all parameters (q, text, input, query, prompt, question) clearly described as aliases. The description adds no new parameter-level semantics; it only says 'fills arguments' generically. Per the rubric, high schema coverage yields a baseline 3, and the description doesn't elevate 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 what the tool does: 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes itself from its sibling ask_pipeworx by explaining it 'EXTRACTS the answer using ONLY what the tool result contains.' This gives a specific verb-like action and differentiates it from the sibling.

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

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

Explicit guidance is given: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also provides an exclusion: 'prefer ask_pipeworx for casual lookups' and mentions the extra cost, making the when-to-use vs. alternative crystal 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 extensive behavioral context beyond annotations: resolver contract, fan-out logic, response shapes, safety mechanisms, resolution-rule risk, and tradeability. No contradiction with annotations (readOnly, idempotent, etc.).

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 very long and detailed, lacking clear structure or sectioning. While comprehensive, it is not concise and could be organized better for easier consumption.

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

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

Despite no output schema, the description fully explains response shapes, resolver contract, parent event extractor, news fields, and safety mechanisms. It covers all necessary context for an agent to understand the tool's behavior.

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

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

Schema coverage is 100% with good descriptions. The tool description adds examples for 'market' and context for other parameters but does not provide significantly new information 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 researches Polymarket bets by pulling relevant data. It accepts multiple input formats and returns an evidence packet and comparison. It is distinct from sibling tools like polymarket_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?

Explicitly suggests use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides classifiers and fan-out examples. Does not explicitly state when not to use, but implies it is for research.

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

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

Even with annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds significant behavioral context: it reveals data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles special cases (off-calendar fiscal years), and describes output format (paired data + citation URIs). 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 paragraphs, relatively concise given the breadth of information. It front-loads example queries and key instructions. Every sentence adds value, though some details could be streamlined or better organized (e.g., data specifics integrated more tightly).

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 absence of an output schema, the description adequately covers return format (paired data + citation URIs). It addresses behavioral aspects, data sources, and special cases. The description is complete for a tool of this complexity, enabling correct invocation without further clarification.

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

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

Schema coverage is 100% with two parameters (type and values). The description adds crucial semantics: explains enum values ('company' pulls 10-K data, 'drug' pulls FAERS data), specifies input format (tickers/CIKs vs drug names), and constrains array length (2–5). This greatly enhances understanding beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs. It provides multiple example queries that trigger the tool, and explicitly distinguishes it from sequential single-entity lookups and other sibling tools like 'entity_profile'.

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

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

The description instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear context for when to use this tool. It also notes results are sorted by primary metric for interpreting terms like 'largest.' However, it doesn't explicitly mention when not to use it or alternative tools beyond sequential lookups.

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 richly discloses behavioral traits beyond the annotations: it performs parallel decomposition across 5,462 tools, returns verbatim evidence with confidence and citations, includes gaps[] for unanswered facets (never invented), has hop field and citation_uri only when resolvable, does semantic excerpting instead of head-truncation, and provides latency expectations (15-60s, up to ~90s for thorough). It also explains depth levels' recovery behavior. This goes far beyond what readOnlyHint/openWorldHint/idempotentHint already tell the agent, and it's not contradicted by annotations.

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

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

The description is dense and information-rich, but every sentence earns its place covering prerequisites, usage context, behavioral details, output structure, and latency. It is front-loaded with the most critical account requirement and uses parens for asides. Slightly long, but for a complex tool with multiple depth modes, this level of detail is justified and well-structured.

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

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

For a complex research tool with no output schema, the description is remarkably complete: it covers account tiers, output structure (findings packet, gaps[], contradictions[], hop field, citation_uri), error/edge behavior (empty gaps for off-catalog topics), performance expectations, and depth-mode semantics. The input schema fully covers parameters, and the description compensates for the absent output schema by detailing the return envelope. No critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it explains what depth levels do behaviorally (re-angles unanswered gaps, chases leads, contradictions scan) and clarifies that question can be broad/multi-part because decomposition is the point. It also adds context that depth:'thorough' is paid. This adds genuine value beyond the schema's brief 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 clearly states the tool's function: grounded multi-source research across Pipeworx's structured data sources in one call. It specifies the resource (1419 structured data sources, 5,462 tools), the verb (researches/decomposes/routes), and its output (findings packet). It also distinguishes itself from siblings like ask_pipeworx and open-web search, so the unique value proposition is unmistakable.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete examples. It also provides when-not-to-use guidance: for single lookups use ask_pipeworx, and for breaking/current news topics prefer ask_pipeworx because deep_research returns empty gaps. It names alternatives (ask_pipeworx, *-news-feeds packs) and covers account prerequisites. This is exemplary usage guidance.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context about the output format (names, descriptions, full input schemas with examples) and notes that results are ready to call directly, which is 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 efficient and front-loaded with the core purpose. It lists many example domains and provides use-case rationale, which earns its length. Slightly verbose but still clear and well-structured.

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

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

Given no output schema, the description fully explains what the tool returns (names, descriptions, full input schemas with examples). Parameter coverage is 100%, and the tool's complexity is low. The description provides all necessary context for an agent to use it correctly.

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

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

The input schema covers all 6 parameters with 100% description coverage, including aliases. The description implicitly references the query parameter ('describing the data or task') but adds no semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses specific verbs and resources (discover, browse, search) and distinguishes itself from siblings by listing many example domains (SEC, FDA, etc.) and emphasizing its role as the first tool to call for discovery.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context and alternatives.

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

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

The description adds significant behavioral context beyond annotations: it fans out across multiple sources, returns specific data fields, makes one parallel call, and discloses the patent sunset soft-fail. All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are consistent and reinforced.

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

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

The description is dense but structured: front-loaded with example queries, then explains behavior and output. While not overly long, it could benefit from bullet points or sections for readability. Still, 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 no output schema, the description explains the return fields (CIK, filings, fundamentals, patents, news, LEI) and includes limitations (patents sunset, name unsupported). It doesn't specify output format (e.g., JSON shape), but it covers the major components adequately.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds marginal value by reiterating that names are not supported and suggesting resolve_entity, but the schema already says that. 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: providing a full cross-source profile of US public companies in one parallel call. It includes example queries and explicitly distinguishes from chaining single-pack lookups. The title 'Entity Profile' aligns well.

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 (user asks for a holistic view) and when-not-to-use (names only; use resolve_entity first). It also mentions the patents sunset limitation. However, it doesn't compare with other sibling tools like compare_entities or deep_research, which could be alternatives for similar holistic queries.

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?

DestructiveHint=true annotated, description confirms deletion. Adds context about clearing sensitive data. No mention of idempotent behavior or error handling.

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 action, 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?

Simple tool with one param, no output schema. Description sufficiently covers purpose, usage, and context.

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

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

Schema covers 100% with description 'Memory key to delete'. Description adds no further meaning 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?

Clear verb+resource: 'Delete a previously stored memory by key'. Distinguishes from siblings 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?

Explicit when to use: stale context, task done, clear sensitive data. Mentioned 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?

All annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) are aligned and the description adds details about the behavior: fetches a page, extracts information, and outputs a text blob. 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 a single, front-loaded paragraph with no redundant words. Every sentence serves a purpose: stating the action, describing the process, and listing use cases.

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

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

Given the simple parameters (2), high schema coverage, and clear annotations, the description fully covers the tool's purpose, behavior, and output format. No external output schema is needed.

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?

With 100% schema coverage, the description does not add significant meaning beyond schema definitions. It mentions 'any URL' and 'maximum of link entries' but lacks additional semantic depth.

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: generate a production-ready llms.txt file for any URL. It explains the process (fetches page, extracts metadata, emits markdown) and distinguishes it from siblings by focusing on a specific output format.

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

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

The description provides explicit use cases (getting client's site indexed, drafting own project, auditing competitors) but does not explicitly state when not to use or compare to alternatives. However, sibling tools are diverse enough that this tool's niche is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is clear. The description adds value by specifying the limit of 5 matches and the field list, plus the keyless access trait, which are behavioral traits 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 extremely concise: two sentences front-loading the core purpose and return details, with no superfluous words. Every sentence adds essential information.

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

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

With a single parameter and an output schema provided, the description covers the key aspects: search behavior, return fields, limit, and accessibility. It is complete for the tool's simplicity, though it could hint at the nature of the search (e.g., fuzzy matching).

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 well-described 'name' parameter including an example. The description does not add additional parameter meaning beyond this baseline, so a 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?

Description clearly states the action (search), target (academic authors), source (Semantic Scholar), and expected output (up to 5 matches with affiliations, paper count, etc.). It distinguishes from siblings like 'search_papers' by focusing on 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 mentions 'Keyless', indicating no API key is needed, which is a usage prerequisite. However, it does not explicitly state when to use this tool over alternatives (e.g., for author lookup vs. paper search), but the clarity of the tool's purpose implies its appropriate 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=true, destructiveHint=false, confirming it is a safe read operation. The description adds value by specifying return fields (abstract, TLDR, authors, etc.) and noting 'Keyless' (no API key required), which enhances 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 only three sentences, each carrying important information: purpose, ID formats, and return fields. No unnecessary words. Highly efficient.

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

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

Given the single parameter, annotations covering safety, and an implied output schema, the description is complete. It covers what the tool does, how to specify the paper, and what to expect in return. No gaps for an agent.

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

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

Schema coverage is 100%, and the schema provides a good description of the parameter. The description reinforces this with examples of valid ID prefixes (DOI, arXiv, CorpusId), adding clarity. However, it largely overlaps with the schema, so the added value is modest.

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

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

The description clearly states the verb 'Get full metadata' for a 'single paper by ID', distinguishing it from sibling tools like 'search_papers' and 'get_paper_citations'. It also provides examples of valid ID prefixes, making the purpose unambiguous.

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

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

The description explains when to use this tool (to get metadata for a single paper by ID) and gives valid ID formats. It does not explicitly mention alternatives or when not to use it, but the context from sibling tool names and common sense fills the gap. Slight lack of explicit exclusion.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds the 'Keyless' behavioral detail and mentions output fields, but does not explain pagination, error handling, or rate limits. The added value is moderate.

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

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

Three sentences: first states purpose and output, second gives usage context, third adds a key feature. No redundant information, front-loaded with core function. 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?

The description explains output fields and usage, but lacks details on ordering (e.g., by citation count?), default limit, and behavior when paper_id is invalid or has no citations. For a simple listing tool with good annotations, it is adequate but could be more 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%: both 'limit' and 'paper_id' are described with types, defaults, and examples. The description does not add further parameter semantics; it only mentions output fields. With high schema coverage, 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 lists papers that cite a given paper, specifying output fields (titles, authors, year, citation counts). This specific verb+resource distinguishes it from siblings like 'get_paper' (retrieves a single paper's details) and 'search_papers' (search by query).

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 says 'Useful for forward citation tracing and finding follow-up work,' clearly indicating when to use it. It also notes 'Keyless,' implying no authentication required. However, it does not explicitly mention when not to use it or suggest alternative tools (e.g., for reverse citations).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds minor value by listing return fields, but does not disclose any additional behavioral traits beyond what annotations provide.

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

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

Two sentences, front-loaded with purpose, and no wasted words. Highly efficient.

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

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

Given the tool's simplicity and the presence of annotations, the description covers return fields and use cases. However, it doesn't mention the optional parameter include_inactive, which could affect the results.

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 for the single optional parameter is 100%, so the description does not need to add param info. It adds no additional 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 it lists the caller's active subscriptions and enumerates returned fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit usage guidance: use to review subscriptions before adding more or to find an id to cancel, which helps the agent decide when to use this tool.

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

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

The annotations are all false and provide minimal safety info, so the description carries the burden. It discloses rate-limiting (5/day), that it's free and doesn't count against quota, that the team reads digests daily, and that feedback affects roadmap. It also instructs not to paste end-user prompts, adding behavioral nuance.

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

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

The description is longer than average but every sentence serves a purpose: purpose, usage triggers, scope exclusion, content guidance, team behavior, and rate limits. It is front-loaded with the core action and well-organized.

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

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

Given the tool's simplicity and the rich schema covering all parameters, the description is complete: it covers when/why to use, scope boundaries, content rules, rate limits, and cost. No output schema is needed, and the description doesn't overpromise.

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 three parameters have 100% schema description coverage, so baseline is 3. The description adds further guidance by telling users to describe issues in terms of Pipeworx tools/packs and not to paste end-user prompts, which complements the schema's per-field descriptions. This raises value slightly above baseline.

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

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

The description opens with a specific action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly differentiates its purpose from any sibling tool by explaining the three feedback categories (bug, feature/data_gap, praise). It unambiguously identifies the resource (Pipeworx 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?

It explicitly states when to use (bug, feature/data_gap, praise) and provides a clear exclusion: only for tools served by this Pipeworx connection, not other MCP servers, with guidance to file those elsewhere. This is exemplary usage direction.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: self-aggregating from CF analytics-engine, no PII, and caching behavior (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?

Two effective paragraphs with front-loaded verb 'Returns'. Every sentence adds value—use cases, window semantics, data source. No fluff or redundancy.

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

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

Given the simple tool (1 optional param, no output schema, rich annotations), the description covers purpose, usage, caching, and data origin. It doesn't detail output format (JSON structure), but that is implied by 'returns' and the context. Almost 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. The description adds meaning by explaining that shorter windows show 'hot right now' and longer windows show 'steady-state demand', which adds practical nuance beyond the enum values.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window (24h, 7d, 30d). It uses specific verbs and distinguishes from sibling tools like discover_tools by focusing on trending usage from other AI agents.

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, and checking alignment with agent activity. Also explains window trade-offs (short for hot, long for steady-state). While not stating when not to use, the guidance is comprehensive and actionable.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds extensive behavioral context: details on semantic anchor (Jaccard similarity), partition filter (placeholder fraction), fill check against live CLOB depth, and response structure. 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 thorough but somewhat verbose, containing multiple sections and detailed explanations. While well-structured and front-loaded with key purpose, it could be more concise; every sentence earns its place but the length may deter quick comprehension.

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 comprehensively explains the response structure (opportunities[], partition_check details, fill check results) and references related tool polymarket_fill_risk. It addresses edge cases (placeholders, low similarity, thin legs) and provides sufficient context for a complex arbitrage 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 describes both parameters with 100% coverage, but the description adds significant meaning beyond the schema: explains accepted formats (slugs, URLs, seed questions), behavior differences between event and topic modes, and internal processing details (walks child markets, searches related events, flattens markets).

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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from siblings by detailing specific algorithms and modes (trending scan, event mode, cross-event mode), providing a specific verb+resource with unique methodology.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It also explains when not to trade (fill check with realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing, offering clear alternatives and exclusions.

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

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

Annotations already declare readOnlyHint=true, and the description adds extensive behavioral detail: caching, model calculations, edge net of slippage, Kelly fractions, diagnostics, and tradeable-edge filters. 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 the main purpose and structured, but it is lengthy with technical details. Every sentence adds value, but could be more concise.

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

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

The description covers the return structure, edge calculation, filtering logic, and diagnostics. Although no output schema, the description compensates well. Minor gaps: does not explain all diagnostic fields in depth.

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

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

Schema coverage is 100% with good descriptions for all 9 parameters. The description adds marginal value for some parameters (e.g., slippage_pp note about fees), but schema already does almost all the work.

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 for opportunities where Pipeworx data disagrees with market price. It explicitly mentions three model families and distinguishes from sibling tools 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 includes usage context ('what should I bet on today') and explains when to adjust knobs like slippage. It lacks explicit when-not-to-use guidance but provides sufficient context for correct invocation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds significant behavioral context: it is based on daily snapshots, has a 60-day TTL, decay numbers from daily closes not intraday, and explains the response structure. This goes well beyond the annotations.

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

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

The description is lengthy but well-structured, using sections for arguments, response, and limits. Every sentence provides valuable information. It could be slightly more concise, but the density is justified by the tool's complexity.

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

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

With no output schema, the description fully explains the return values (tracked, expired, snapshot_dates) and limitations (TTL, decay computation). This makes the tool's behavior completely understandable for an AI agent.

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

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

The input schema has 100% coverage with descriptions for both parameters. The description adds extra context: the clamp range for days (2-30) and the notion of 'snapshot family' for window. This enhances understanding, making it 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's purpose: edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' It uses specific verbs (answers, tracks) and resource (edge persistence/decay). It distinguishes from sibling tools like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description implies when to use this tool (e.g., when needing historical edge trends) but does not explicitly state when not to use it or compare to alternatives. It could be improved by mentioning direct alternatives like polymarket_edges for current edge 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?

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: walks the ladder, returns verdicts (clean/degraded/cannot_fill), describes partial fill risks, and explains the auto side detection for baskets. No contradiction with annotations.

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

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

The description is well-structured with clear sections for single-market and basket modes, and is front-loaded with purpose. However, it is somewhat verbose with run-on sentences (e.g., the long paragraph starting 'SINGLE-MARKET:'). Could be more concise.

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

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

For a tool with 4 parameters, no output schema, and two modes, the description covers purpose, usage, behavioral risks, and key return fields. It explains constraints (required one of market/event, default size, clamp). Minor missing details like output format, but not 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?

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains the auto-detection for basket side, the interpretation of size_usd (settlement notional for basket), and default values. It also describes return fields not in the output schema, compensating for its absence.

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

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

The description explicitly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, making it 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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the risks of not using it and specifies when to use single-market vs. basket mode.

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 show readOnlyHint, idempotentHint, destructiveHint, ensuring safety. The description goes far beyond by detailing internal logic (leg-by-leg comparison), failure modes (compatibility_warning conditions), temporal alignment checks, and counter details (skipped_cross_type/subtype). 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-structured with front-loaded purpose, clear sectioning (MODES, RESPONSE, SAFETY FIELDS). It is somewhat lengthy but each sentence serves a purpose. Minor improvement possible for skimmability, but overall efficient.

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

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

Given no output schema, the description compensates by thoroughly explaining the response structure including leg-by-leg prices, spread, safety fields, and counter details. It covers all necessary aspects for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description adds value by explaining the interaction between topic and explicit overrides, and listing the topic shortcuts explicitly. This compensates for the lack of enums in schema.

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

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

The description clearly states it computes the spread between Kalshi and Polymarket for the same resolving question, with specific verb 'cross-venue spread' and resource. It distinguishes from siblings by focusing on this specific pair of prediction markets, unlike other tools that deal with individual venues or other entities.

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

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

The description explains two modes (topic shortcuts and explicit tickers) with examples, and provides guidance on when results are meaningful via compatibility_warning and temporal_alignment fields. It explicitly notes that most pre-mapped topics return warnings, setting expectations and preventing misuse.

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 (read-only, idempotent, not destructive), describes scoping by identifier and behavior when argument is omitted. No contradiction.

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

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

Two sentences pack main action, usage, examples, scope, and pairing. Front-loaded and 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?

For a simple read-only tool with one optional parameter and no output schema, the description fully covers behavior, usage, and scope.

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 'key' fully (100%), description adds usage nuance: omit to list all keys. Adds value 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?

Clearly states the tool retrieves or lists saved values via 'remember', with specific examples (ticker, address, research notes). Distinguishes from siblings 'remember' and 'forget'.

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

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

Explains when to use (look up prior context without re-deriving) and mentions pairing with related tools. Could add explicit 'when not to use'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds valuable context: return fields, mark_read behavior (flagging events read), and polling suitability.

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

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

Four sentences covering purpose, filtering, mark_read, polling, and alternative access. No fluff, efficiently front-loaded.

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

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

Given 5 optional params, no output schema, and strong annotations, the description covers usage, return details, side effects, and alternative access. Fully sufficient for agent invocation.

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

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

Schema coverage 100% with descriptions. Description reinforces with examples (type 'sec_8k', since ISO timestamp, mark_read effect) but does not add new semantic depth 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?

Clear verb+resource: 'Pull fired events from your subscription feed.' Specifies return content (source, citation_uri, payload) and distinguishes from siblings like list_subscriptions and subscribe.

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 filtering examples (type, since) and notes alternative access via GET registry.pipeworx.io/alerts.json. Lacks explicit when-not-to-use, but context is sufficient.

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

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

The description discloses thorough behavioral details: fans out to multiple sources, explains failure modes (USPTO soft-fail, GNews fallback), and describes the return format (structured changes grouped by source, total_changes count, citation URIs). Annotations already declare safe, idempotent behavior, and the description adds valuable context.

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

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

The description is a single, dense paragraph that packs a lot of information efficiently. It front-loads query examples and key usage notes. While clear, it could be slightly improved with bulleted lists for readability, but it remains concise and well-organized.

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

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

Given no output schema, the description adequately explains the return structure (changes grouped by source, total_changes, citation URIs). It covers major behaviors and constraints. Minor gaps exist (e.g., pagination or max results), but overall it is sufficient for an agent to understand the tool's capabilities.

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 extra value by explaining the 'since' parameter's date vs relative format, recommending '30d' or '1m' for monitoring, and clarifying that 'value' accepts tickers or CIK numbers. This justifies a score above baseline.

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

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

The description clearly defines the tool as a change feed for companies, fanning out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It provides concrete query examples and explicitly distinguishes from the sibling 'entity_profile' tool, making its purpose unmistakable.

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

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

The description gives explicit guidance on when to use this tool ('what's new' queries) and when not to (use entity_profile for static profiles). It also explains fallback behavior for news sources and provides usage examples for the 'since' parameter, including a recommendation for typical monitoring.

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 scoping by identifier, persistence differences between authenticated and anonymous users, and pairs with recall/forget. All annotations are consistent (idempotentHint, destructiveHint) and description adds useful 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?

Description is moderately long but front-loaded with the core purpose. Every sentence contributes information about usage, scoping, and pairing. Slightly wordy but no redundancy.

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

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

For a simple 2-param tool with no output schema, the description completely covers purpose, use cases, lifecycle, scoping, and pairing with siblings. No gaps for an agent to misinterpret.

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 3. The description adds value by explaining the key-value concept and naming conventions (examples like 'subject_property'), going beyond schema type strings.

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 pair ('save data the agent will need to reuse later') and distinguishes itself from siblings like recall and forget by explaining the store-retrieve-forget lifecycle.

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 tells when to use ('when you discover something worth carrying forward') and mentions complementary tools (recall, forget) but does not explicitly say when not to use it.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: it cascades through multiple lookup endpoints, returns citation URIs, auto-disambiguates input, and details the return structure per entity type. This goes beyond what annotations convey, though it stops short of discussing failure modes or edge cases like ambiguous names.

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 that immediately convey intent. It then separates supported types into a clear structure. While slightly long, every sentence carries useful information—no filler. The only minor nit is the run-on opening sentence, but overall it's well-organized and scannable.

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?

Without an output schema, the description compensates by listing the exact return fields for each entity type (ticker, CIK, company_name for companies; RxCUI, ingredient, brand for drugs) and mentions citation URIs. It also explains the internal cascading behavior. It's missing explicit error/not-found handling, but for a lookup tool with strong annotations and detailed schema, this is largely 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 includes detailed value descriptions. The tool description adds meaning by explaining the return values associated with each type enum (e.g., company returns ticker + CIK + name) and by noting auto-disambiguation, which the schema does not mention. This supplements the schema effectively, elevating it above the baseline.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers (ticker, CIK, RxCUI) and explicitly says 'Use FIRST whenever you have a name but need an ID.' This distinguishes it from sibling tools like entity_profile or compare_entities, which presumably operate on already-resolved entities.

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

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

Provides clear when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups, giving context on efficiency. However, it doesn't explicitly state when NOT to use it or name specific sibling alternatives, so it lacks the 'when-not/alternatives' completeness for a 5.

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

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

The description adds behavioral context beyond annotations (readOnlyHint, etc.) by detailing the probe process via ai_visibility_check, ranking, and output fields (score, confidence, signal density). It fully aligns with annotations, with 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?

Three sentences: first states purpose, second explains mechanism, third provides use case and output. Front-loaded, every sentence adds value, no redundancy.

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

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

Despite no output schema, the description explains the return value (ranked list with score, confidence, signal density). It covers the subject/competitor distinction and internal call to ai_visibility_check, providing sufficient context for a comparative 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 detailed parameter descriptions; the tool description does not add new parameter-specific information beyond what the schema already provides. Baseline 3 is appropriate as the schema carries the burden.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb 'compare' and resource 'AI visibility'. It distinguishes from siblings like ai_visibility_check by emphasizing side-by-side ranking and competitive audit use case.

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 concrete use case ('competitive AI-marketing audits') and example ('does Claude know about us as well as our competitors?'). It implies when to use (multiple entities comparison) but lacks explicit guidance on when not to use or alternatives like ai_visibility_check for single entities.

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 behavioral details beyond annotations: fans out across deps.dev and bundlephobia, partial failures, first measurement delay, return structure. No contradiction with annotations.

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

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

Well-structured and front-loaded, but slightly verbose with ecosystem fallback details. Still clear and 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?

No output schema, yet description fully details return structure (summary fields, per-advisory, links, alternatives) and edge cases (partial failures, delay).

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

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

Schema coverage is 100%; description adds context on scoped packages and version defaulting. Useful but not essential.

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 specifies a composite check for npm packages covering license, advisories, bundle size, etc. Distinguishes from siblings by clearly defining its scope (npm ecosystem) and purpose.

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

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

Explicitly states when to use: when agent asks about safety, popularity, size, or cost. Mentions NPM-only and fallback for other ecosystems.

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 safety hints; description adds value by specifying 'keyless' access and the source (Semantic Scholar) and scale (200M+ papers). 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?

Three concise sentences, no redundancy. Front-loaded with the main action, then specific use case, then options and keyless info.

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 an output schema present, the description doesn't need to detail returns. It covers purpose, usage, parameters, and uniqueness (keyless). Complete for a search tool.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description does not add significant new meaning beyond what the schema provides.

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

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

The description clearly states the tool searches 200M+ academic papers on Semantic Scholar by keyword or exact title, and lists returned fields. It distinguishes itself from siblings like 'get_paper' and 'get_paper_citations'.

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 prefer this tool, e.g., citation count queries, and hints at filtering options. Provides clear context without mentioning alternatives but the use case guidance is strong.

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

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

Discloses technical details beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (truncated and flagged).' Adds value since annotations only indicate safety/idempotency.

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, front-loaded with purpose, then usage, then technical details. Every sentence adds value; 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?

Given 3 parameters and no output schema, description explains return (passages with offsets and scores) and includes limit info. References sibling tool for context. Complete for intended use.

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

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

Schema coverage is 100% with descriptions, but description adds examples for query (e.g., 'supply-chain risk') and specifies text's max chars. Provides default for limit. Adds meaning 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?

Clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with whole-document tools.

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

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

Explicit when-to-use: 'Use when the record is too big to cram into the prompt.' Also suggests pairing with another tool. Lacks explicit when-not-to-use scenarios, but provides clear context.

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

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

Discloses authentication requirements, type-specific behavior, delivery channel constraints (phone verification, 10/day SMS cap, webhook auto-disable after failures), and return value. Does not contradict annotations.

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

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

Well-structured with front-loaded purpose, but lengthy due to extensive examples; every sentence adds value but could be slightly more concise.

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

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

Covers prerequisites, all types, delivery channels, return value, and constraints (e.g., auto-disable). No output schema, but return value is mentioned. Nearly complete for a create tool.

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

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

Schema coverage is 100%, but description adds concrete examples, constraints, and explanations for each type and delivery option, far exceeding the schema descriptions.

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription', returns the new subscription id, and distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

It provides prerequisites (OAuth account), delivery options with setup instructions, but no explicit comparison to sibling tools beyond the implicit separation of creating vs. listing/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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it is the onboarding entry point, returns examples with tool+argument shape from the live catalog, and describes the behavior with and without the topic parameter. 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 relatively long but well-structured with front-loaded key information, parentheses for categories, and no redundant sentences. Each sentence adds value, though it could be slightly more concise.

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

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

Given the tool's simplicity (1 optional param, no output schema, extensive annotations), the description is complete. It covers what the tool does, when to use it, how to use it (with examples), and what to expect in the response.

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

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

Schema coverage is 100% and the description adds meaning by explaining the optional topic parameter's allowed values (e.g., finance, pharma, betting) and the effect of omitting it. This enriches the schema beyond basic type 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 clearly states the tool returns category-bucketed example questions to help new users understand what they can ask Pipeworx. It distinguishes itself from siblings like ask_pipeworx and discover_tools by positioning itself as the onboarding entry point.

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 advises using this tool 'FIRST when you do not yet know what Pipeworx can do for you' and explains it helps learn to call meta-tools. While it doesn't explicitly state when not to use it, the context makes the usage clear.

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

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

Adds critical context beyond annotations: ownership enforcement, deactivation semantics, and historical data availability. Consistent 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?

Three efficient sentences, front-loaded with action, no wasted words.

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

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

For a simple tool with one parameter and no output schema, description covers all necessary context: purpose, constraint, and side effects.

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

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

Schema already describes id; description adds that it is returned by subscribe, providing useful origin 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?

Clearly states verb 'cancel' and resource 'subscription by id'. Differentiates from sibling tools 'subscribe' and 'list_subscriptions'.

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

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

Explains ownership enforcement and that deactivation not deletion preserves history. Lacks explicit when-not-to-use or alternatives.

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

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

Description discloses two behavioral paths (exact percent-delta math for financial claims, grounded pipeline for others), return structure (verdict, actual value, citation), and tolerance customization. Annotations already declare readOnlyHint, idempotentHint, openWorldHint; description adds meaningful operational detail 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?

Description is lengthy but every sentence serves a purpose: trigger examples, routing logic, return format, efficiency notes. Could be slightly tighter, but front-loads critical information and maintains clarity.

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 fully documents return values (verdict types, actual value, citation) and explains the two processing paths. All aspects of tool behavior are covered for an agent to use it correctly.

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

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

Schema coverage is 100%, yet description adds significant context beyond schema: explains how tolerance_pct overrides implied default, suggests value ranges (0.5-50) and use cases (1-2 for hallucination detection). This materially aids correct parameter 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?

Description clearly states the tool's purpose with explicit trigger phrases ('Is it true that...', 'fact check', 'verify the claim'), identifies the specific verb-resource pair (validate claim), and distinguishes between two distinct routing paths (SEC EDGAR vs grounded pipeline). No sibling tool duplicates this functionality.

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

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

Explicitly states when to use ('whenever the agent needs to check whether something a user said is factually correct') and provides contextual guidance on routing. Missing explicit when-not-to-use scenarios, but clarity is high given the tool's narrow focus.

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