Datacite

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

Annotations already mark it as readOnly, openWorld, idempotent, and non-destructive. The description adds critical behavioral details: cost implications (free for Workers AI, BYO key for Anthropic), the scoring range, return structure (per-model {score, confidence, signals, raw_response} + combined view), and the API key handling. This exceeds 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?

The description is a single, efficient paragraph that front-loads the core purpose and then adds necessary details about defaults, costs, and return structure. Every sentence delivers useful information with no redundancy.

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

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

Despite no output schema, the description fully explains the return format (per-model {score, confidence, signals, raw_response} + combined view). It covers inputs, defaults, optional parameters, and use cases. The tool is well-documented for its complexity.

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

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

The input schema has 100% description coverage, so baseline is 3. The description adds value by explaining the default model behavior, the necessity of '_apiKey' for Anthropic, and how 'context' aids disambiguation. This extra context improves parameter understanding.

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

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

The description explicitly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility from 0-100, naming the default model and optional Anthropic integration. This clearly distinguishes it from sibling tools like 'entity_profile' or 'scan_competitor_ai_presence'.

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

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

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' While it does not explicitly state when to avoid this tool, the use cases are well-defined and imply appropriate scenarios.

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

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

The annotations already establish read-only, open-world, idempotent behavior. The description adds meaningful extra context: it orchestrates thousands of tools, fills arguments automatically, draws from verified sources, and returns stable citation URIs. 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 front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and every major alternative earns its place. It is long but justified for a broad routing tool; however, the ending contains a garbled sentence about DBPedia/Wikidata and some phrasing such as 'with one exception: e.g.' is awkward.

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

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

For a one-required-parameter tool with no output schema, the description covers when to use it, when not to, what it does, what output to expect, and which siblings to choose. The unclear final sentence and the absence of fallback behavior when no source matches are minor but real 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%: all six parameters are documented as aliases for the same natural-language question field. The description reinforces what kinds of questions are acceptable but does not add material parameter-level semantics beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool's job: route a natural-language question to the right one of 5,798 tools and return a structured answer with pipeworx:// citation URIs. It also separates itself from web search and several sibling research tools.

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

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

The description explicitly says to prefer this tool over web search for factual/structured-data questions, lists trigger phrasings like 'what is', 'look up', 'find', and 'current', and names alternatives with conditions: deep_research, bet_research, ask_pipeworx_grounded, web_search_first, and chat.

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

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

The description goes beyond the annotations by disclosing beta status, current candidate state, the retirement date, and the important fallback behavior: this is a full working router, not a degraded stub. No contradiction with the readOnly, openWorld, idempotent, non-destructive 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?

Four dense, front-loaded sentences: definition, current status, usage instruction, and fallback behavior. Every sentence earns its place and there is no filler, despite covering a lot of beta-specific nuance.

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

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

Covers current behavior, exact relationship to the stable sibling, when to choose it, and what happens if no candidate is active. It also notes the same response shape as ask_pipeworx, which is enough given that tool's similarity and the lack of an output schema.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for quetion. The description adds only that arguments match ask_pipeworx, which is useful but not necessary to understand the parameters. Baseline 3 is appropriate because the schema already carries the semantic weight.

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?

States a specific verb+resource: it is a beta universal router identical to ask_pipeworx except with live candidate routing improvements. It clearly differentiates from the stable sibling by naming ask_pipeworx and the experimental edge.

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

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

Explicitly directs the agent to use it exactly like ask_pipeworx when it wants the newest routing, and says results are compared against the stable router. It also notes that no candidate is active now, so behavior currently matches the stable tool exactly, which helps with tool selection.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses the full return contract including evidence as a verbatim quote, confidence, source, fetched_at, and a structured refusal with enumerated refusal_reason values. It also reveals the extra LLM call cost and the restriction to tool-result content, which annotations do not convey.

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

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

The description is dense but every sentence contributes: identity, routing behavior, output/refusal contract, usage criteria, and cost trade-off. It is front-loaded with the key differentiator ('Hallucination-resistant answer mode for high-stakes reads') and avoids repetition.

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

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

Given there is no output schema, the description compensates by specifying the exact success and refusal objects. It covers purpose, routing scope, data source behavior, use cases, when not to use it, and cost — while the input schema covers the only required parameter. An agent has enough to invoke and interpret the result correctly.

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

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

Schema description coverage is 100% and the input schema already defines the single required question parameter with all six aliases. The description adds no parameter-level detail beyond that, so it meets the high-coverage baseline but does not go further.

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 names a specific mode ('Hallucination-resistant answer mode for high-stakes reads') and explains the exact mechanism: same routing as ask_pipeworx, then extraction only from tool results. This clearly distinguishes it from the sibling ask_pipeworx and even names that sibling as the comparison 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?

It explicitly states when to use the tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with concrete high-stakes examples. It also gives the alternative selection rule: 'prefer ask_pipeworx for casual lookups' and notes the extra cost.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, etc., and the description adds extensive behavior: fan-out process, response shapes, market match confidence levels, parent event extraction, news fallbacks, safety short-circuits, and resolution rule risk. 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 long but well-structured with headings and examples. Every sentence provides value for the tool's complexity. It is front-loaded with purpose and then details response shapes and edge cases.

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

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

Given the complexity of 3 parameters and no output schema, the description covers input format, processing details, response structure, edge cases (closed markets, low-confidence), and resolution rules comprehensively. It leaves little ambiguity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context for the market parameter (slug, URL, question) and explains depth and include_raw behaviors, but it does not significantly extend 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 a Polymarket bet by pulling Pipeworx data in one call. It specifies the verb (research), resource (Polymarket bet), and input formats. It distinguishes from sibling tools like polymarket_arbitrage, which focus on analysis rather than data gathering.

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 tells when to use the tool: for questions like 'should I bet on X' or 'is there edge in Z'. It provides examples and warns about inspecting market_match_confidence before trusting analysis. However, it does not explicitly mention when NOT to use it or list alternative tools.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description reveals that for 'company' it pulls specific financial metrics (revenue, net income, cash, debt) with correct fiscal year handling, and for 'drug' it pulls adverse-event counts, approval counts, and trial counts. It also states results are sorted by primary metric and includes citation URIs, adding significant behavioral context.

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

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

The description is concise and front-loaded with trigger phrases and imperative guidance. Every sentence provides necessary information without redundancy, making it efficient for an AI agent to parse and understand.

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 return values (paired data + pipeworx:// citation URIs) and covers both entity types comprehensively. It also estimates the efficiency gain (replaces 8-15 lookups), providing sufficient context for tool selection.

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 clarifying 'values' uses tickers/CIKs for companies and drug names for drugs, and explicitly states the min/max limits (2-5) already in schema, but also explains the purpose of the 'type' enum, enhancing clarity beyond the schema.

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

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

Description uses specific verbs ('compare', 'side-by-side comparison') and clearly states the resource (2-5 companies or drugs) and action. It further specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and distinguishes from sequential lookups, 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?

Description explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides natural language triggers (e.g., 'compare X and Y', 'which is bigger'). It lacks explicit when-not-to-use scenarios, but the context is clear enough for most use cases.

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

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

It goes far beyond the annotations, disclosing decomposition, parallel routing, return packet structure, gap handling, contradictions[], citation_uri reliability, semantic excerpting, and latency expectations. There is no contradiction with the readOnly/openWorld/idempotent annotations.

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

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

The description is long but densely packed, front-loading the auth requirement and routing guidance before the mechanism and output details. Every sentence adds useful behavioral or selection information, and the detail compensates for the absence of an output schema.

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

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

Given the tool's complexity and lack of an output schema, the description is thorough: it covers inputs, output packet fields, citation semantics, failure transparency, authentication, pricing, latency, and when not to use it. An agent has enough context to select and invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds extra value by noting that thorough requires a paid plan, that quick=3 facets, and that standard/thorough include contradiction scanning, enriching the agent's understanding beyond the enum 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 operation: grounded multi-source research across Pipeworx's 1517 structured data sources in one call, with explicit decomposition and parallel routing. It also distinguishes itself from open-web search and from ask_pipeworx for single lookups, making its scope unambiguous.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use ask_pipeworx instead when not signed in, and use ask_pipeworx for single lookups. It also names the tool's best-fit case: broad, multi-part questions over structured 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses that it returns 'top-N most relevant tools with names, descriptions, and full input schemas' and that results are 'ready to call directly'. 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 fairly long but well-structured, front-loading the core purpose, then listing domains, return behavior, and usage guidance. Each sentence adds value with minimal 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 6 parameters with full schema coverage and no output schema, the description adequately explains return values (top-N tools with schemas) and provides examples. No obvious gaps for this 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% with all parameters described. The description mentions aliases for query and provides usage examples, but adds no extra semantic detail beyond what the schema already 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 states a specific verb 'Find tools by describing the data or task' and lists diverse domains (SEC filings, financials, etc.), clearly distinguishing it from sibling tools which are specific actions or data sources.

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 directs when to use: 'Call this FIRST when you have many tools available and want to see the option set'. It implies discovery before action, though it does not explicitly state 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?

Despite annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds substantial behavioral detail: it fans out across nine sources, explains that empty sections indicate real absence of data (not errors), discloses the USPTO API sunset and soft-fail, and clarifies that FDA products only cover biologics. This goes far beyond what annotations imply and gives the agent correct expectations on failure modes and partial results.

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

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

The description is long but every sentence earns its place. It front-loads the most critical information (trigger phrases and the mandate to prefer this tool), then systematically enumerates the sources and return fields. The use of semicolons and clear delineation of sections (recent_filings, fundamentals, patents, etc.) keeps it navigable. 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?

With no output schema, the description must explain the return structure and edge cases, and it does so thoroughly: it lists each section of the response (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI), explains the URI format, and covers failure modes (sources_failed, empty sections, private company). An agent has everything it needs to call the tool correctly and interpret 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 already provides 100% coverage for both parameters, so baseline is 3. The description adds value by clarifying that type accepts 'company' and 'ticker' interchangeably, and that value can be a ticker, CIK, or company name with resolution via EDGAR. It also notes private-company behavior. This is meaningful extra context, but it still leans on the schema for the basic parameter shapes, so a 4 is appropriate.

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

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

The description opens with concrete trigger phrases and states the core function: a full cross-source profile of a US public company in one parallel call. It explicitly contrasts with chaining single-pack lookups, clearly distinguishing it from sibling tools like resolve_entity or deep_research. Every sentence reinforces the purpose, making it unmistakable what this tool does.

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

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

Provides explicit when-to-use guidance: 'when the user asks for a holistic view' and 'ALWAYS PREFER over chaining single-pack...' It also covers when not to expect data (private companies, FDA small-molecule only) and explains fallback behavior. The examples of natural-language triggers are practical and help an agent recognize the right context. This is a model of 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 declare destructiveHint=true; description adds the action 'delete' but no further behavioral details beyond the schema and annotations.

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

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

Two sentences, front-loaded with core action, zero 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?

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage conditions, and relationship to sibling tools.

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

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

Schema coverage is 100% and description mentions 'by key', but the schema already defines 'Memory key to delete', so no additional value beyond 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?

Clearly states the tool deletes a memory by key, distinguishing it from siblings like 'remember' and 'recall'.

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

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

Explicitly specifies when to use (stale context, task done, clear sensitive data) and mentions companions, though no 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description explains the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It adds context about output format and placement, enhancing transparency without contradiction.

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

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

Three sentences, each earning its place: first states purpose and target, second describes the process, third lists use cases. No fluff, front-loaded, and efficiently 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 the simple tool (2 params, no output schema), the description covers purpose, process, output format, and use cases. It lacks error handling or accessibility prerequisites, but for a generation tool, it's sufficiently complete. Annotations further cover safety aspects.

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 minimal new meaning: it mentions 'for any URL' and implies max_links controls link count. Since schema already explains parameters, the description doesn't significantly augment understanding.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. It specifies the verb (generate), resource (llms.txt), and target (any URL). It also distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation.

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

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

The description lists specific use cases: getting a client's site indexed, drafting for own project, auditing competitor's AI view. While it doesn't explicitly exclude scenarios, the examples provide clear context. It could be improved by mentioning alternatives like scan_competitor_ai_presence for auditing.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds detail on returned metadata fields, 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?

Two sentences: first states action, second lists return fields. No wasted words.

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

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

Given the simple tool with one parameter, output schema present, and comprehensive annotations, the description thoroughly covers purpose and returns.

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 the 'doi' parameter with an example. Description adds no additional semantic detail 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?

Clearly states it fetches a single DOI record and lists specific metadata returned, distinguishing it from 'search_dois' for multiple records.

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

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

Explicitly describes fetching a single record, implying usage when a specific DOI is known, but does not explicitly contrast with sibling 'search_dois'.

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 the safety and behavioral profile. The description adds that repositories are DataCite-registered and support filtering, but no additional behaviors (e.g., pagination details, rate limits) are disclosed. The description adds value but does not significantly expand 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-loaded with the main purpose, and includes an example and a use case. No unnecessary words; every sentence earns its place.

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

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

Given the low complexity, full schema coverage, and presence of an output schema, the description is fairly complete. It provides examples and a clear use case. However, it could optionally mention pagination behavior (though schema covers defaults) and briefly note the response structure, but the output schema likely covers that. Minor gap.

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 each parameter documented (page, query, page_size). The description only mentions 'filter by query' which is redundant with the schema. It adds no new semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists DataCite-registered data repositories, provides concrete examples (Zenodo, Dryad, Figshare), and distinguishes itself from sibling tools which are unrelated to repositories. The verb 'list' and resource 'repositories' are specific.

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

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

The description explicitly says it's useful for 'where do I deposit a dataset' lookups, giving a clear context of use. It does not mention alternatives or when not to use, but sibling tools do not compete, so this is a minor omission. The guidance is clear and actionable.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds specific return fields and the scope 'active subscriptions,' but does not elaborate on queries or limits. Still, it complements annotations well.

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

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

Two sentences: first states action and output, second provides usage context. No wordiness, and key information is 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 one optional parameter, strong annotations, and no output schema, the description is nearly complete. It explains purpose, output fields, and usage. Minor omission: no mention of result ordering or limits, but not critical for this tool.

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

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

Schema coverage is 100%, so description need not repeat parameter details. The parameter 'include_inactive' is documented in the schema, and the description adds no extra semantic 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 it lists the caller's active subscriptions and specifies the returned fields (id, type, etc.). It also distinguishes from sibling tools like subscribe and unsubscribe by providing use cases.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This guides the agent effectively, though alternatives are implicitly differentiated rather than named.

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

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

Annotations only provide basic hints, but the description goes far beyond: it discloses rate-limiting (5 per identifier/day), confirms no quota impact, explains the claim_token return and follow-up flow, and notes daily digest reading. 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?

Although long, every sentence earns its place: purpose, usage conditions, exclusions, claim_token workflow, SLA, rate limit, and cost. Front-loaded with intent and no filler or redundancy, making the length justified for this non-obvious tool.

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

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

Even without an output schema, the description explains what the tool returns (claim_token initially, status/changes later). It covers scope boundaries, invocation behavior, rate limits, quota cost, and the feedback lifecycle, making the tool fully understandable and safely usable 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%, but the description adds real semantic value: it maps type values to concrete scenarios (bug, feature, data_gap, praise), explains how to use claim_token to read prior replies, and instructs users to reference Pipeworx tools/packs which aligns with the context object. This significantly enriches the bare schema.

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

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

Description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the verb+resource and unique purpose. It distinguishes itself from all sibling tools by focusing exclusively on feedback for Pipeworx-provided tools, with no overlap.

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 guidance covers bug, feature/data_gap, and praise scenarios. It also provides strong when-not-to-use guidance for tools from other MCP servers, plus instructions on what to include (Pipeworx tools/packs) and how to follow up with claim_token.

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 false. Described adds no-PII, self-aggregating from CF analytics, caching (5min-1h). No contradictions.

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

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

Two paragraphs, no wasted words. Use cases are bulleted. Additional details (caching, no PII) are brief but informative. Perfectly front-loaded.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers return values (tools, packs, volume), data source, caching, and privacy. No gaps.

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

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

Only one parameter (window) with enum, schema description is 100% coverage. Description adds value by explaining trade-offs between short and long windows ('hot right now' vs 'steady-state demand').

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

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

Description clearly states the tool returns top tools, top packs, and call volume over a recent window. The verb 'Returns' and resource 'trending data on Pipeworx' are specific. It distinguishes from siblings like discover_tools or ask_pipeworx.

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

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

Explicitly lists three concrete use cases (discovering hot data, confirming canonical tool, aligning use case). No explicit when-not-to-use, but context is clear. Window parameter effects are explained.

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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the tool is safe and idempotent. The description adds valuable behavioral context, such as the fill check mechanism that checks against live CLOB depth and warns when an opportunity is not realizable ('do not trade it'). It also explains semantic anchor and partition filter behaviors. 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 comprehensive but not overly verbose. It is well-structured: starts with the general purpose, then details each mode, and ends with response structure and fill check. Each sentence adds value. While it is relatively long, the density of information justifies the length. A slight trim could make it more concise, but it remains effective.

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

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

Given the complexity of the tool (two modes, fill check, response format), the description is very complete. It covers the input, behavior, and output (response: opportunities array, partition check). It explains edge cases like placeholders filtered and when to avoid trades. With no output schema, the description fully compensates by describing the return structure. It also references a sibling tool for customization.

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 provides 100% coverage with descriptions for both parameters. The description adds further semantics, explaining that 'event' expects a Polymarket event slug or URL, and 'topic' expects a seed question. It elaborates on the modes and what happens in each case, including details like 'walks child markets' and 'searches related events.' This adds significant meaning beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) with concrete examples, and the verb 'find' accurately captures the read-only nature. The purpose is specific and differentiated from siblings like polymarket_fill_risk.

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 parameter: 'event (recommended for a specific market)' and 'topic (for cross-event scanning).' It gives examples of event slugs and seed questions, and notes that event mode is preferred. It also directs users to polymarket_fill_risk for custom sizing, providing an alternative tool. This satisfies the 'when to use vs alternatives' requirement.

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 extensively details behavioral aspects beyond annotations, including caching (1h at KV level), model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), edge calculation (edge_pp_net after slippage), Kelly sizing (kelly_fraction capped at 0.25), 24h move warnings, and diagnostics. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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 (multiple paragraphs) but well-structured with bold section headers for segments and knobs. It is front-loaded with the purpose. However, it could be more concise; some details (e.g., specific model parameters like alpha values) might be excessive for an AI agent's initial selection.

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

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

Given the complexity (9 parameters, no output schema, multiple model families), the description is thoroughly complete. It covers return segments (by_segment), diagnostics (_diagnostics with funnel counters), caching behavior, and exclusion notes (Fed bets). No gaps are apparent.

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

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

Schema coverage is 100% with detailed descriptions for all 9 parameters. The tool description adds some context (e.g., explaining tradeable-edge knobs), but it does not significantly enhance parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool scans Polymarket markets to find discrepancies between Pipeworx data and market prices, with a specific use case 'what should I bet on today'. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge detection using multiple model families.

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

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

The description provides clear guidance on when to use (discovering opportunities without paging) and includes details on knobs for filtering (min_liquidity, max_spread_pp). However, it does not explicitly name alternative tools or state when not to use this tool, leaving some ambiguity for an AI agent.

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

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

The description goes beyond annotations by detailing behavior: it uses daily snapshots, computes trend and decay, returns tracked, expired, and snapshot_dates. It explains that decay is computed on the absolute edge_pp_net, signed by trade direction, and mentions limitations (60-day TTL, non-intraday data). No contradictions with annotations.

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

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

The description is well-structured with clear sections (RESPONSE, LIMITS) and is concise given the amount of information. Every sentence adds value, though it could be slightly tighter.

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

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

The description covers return values (tracked, expired, snapshot_dates) with details on fields, trend, decay, and limitations. It explains the signed nature of edge_pp_net. Lacks explicit examples but is sufficient for an agent to understand tool usage and output.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context about default values and snapshot families ('1wk'), but does not significantly enhance understanding beyond the schema's 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 identifies the tool's purpose: providing edge persistence and decay telemetry from polymarket_edges snapshots. It answers a specific question about edge duration and contrasts fresh vs. old edges, distinguishing it from siblings like polymarket_edges which likely provide current snapshots.

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 the tool: to understand how long an edge has existed and if it is shrinking. It contrasts a fresh wide edge with a 3-week-old one, implying when not to rely on current edge data. Limitations about history depth and TTL are also provided. However, it does not explicitly name alternative tools for current edges.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating a safe read operation. The description adds detailed behavioral context (walks the ladder, returns verdict, warns about partial basket fills turning arb into directional position) without contradicting annotations.

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

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

The description is comprehensive but well-structured, with clear sections for single-market and basket modes. While lengthy, every sentence adds necessary detail. It could be slightly more concise, but the structure aids readability.

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

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

Given the tool's complexity (two modes, many return fields) and the absence of an output schema, the description fully enumerates return values for both modes (top-of-book, VWAP, slippage, verdict, etc.) and warns about risks. No gaps identified.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value by explaining the dual modes (single-market vs. basket) for parameters like 'side', 'event', 'market', and 'size_usd', clarifying defaults and interpretation beyond the schema.

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

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

The description clearly states the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate its role.

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

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

Explicitly provides when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable, partial fills cause directional risk), making it easy for an agent to decide.

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

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

Annotations already mark the tool read-only and idempotent; the description goes well beyond by disclosing that pair matching uses keyword/word overlap rather than a shared resolution source, that compatibility codes can be non-empty even on returned pairs, that Kalshi fees are not modeled and all spreads are gross, and that null temporal_alignment means 'unknown' rather than 'aligned'. This is exceptional candor about the tool's limitations.

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

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

The description is long, but the tool is complex and has no output schema, so nearly every sentence carries needed caveats. The core purpose is front-loaded and safety fields are clearly labeled. Minor repetition (temporal alignment semantics are covered twice) prevents a perfect structure score.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers both input modes, matching behavior, return fields (top_spreads_pp, compatibility_codes, temporal_alignment, skipped counters), fees, gross-vs-net caveats, and how to interpret edge cases. An agent has everything needed to invoke the tool correctly and interpret its 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?

All three parameters are documented in the schema (100% coverage), giving a baseline of 3. The description adds meaningful semantics: `topic` auto-fetches the matching event on each venue, explicit parameters override the mapped side, both modes run the identical matcher, and explicit mode requires both a ticker and a slug. This is real value beyond the schema's 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 identifies the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question. It distinguishes itself from likely siblings by naming both venues and explicitly framing the delta as a real signal only when bet shapes are equivalent.

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 tool explains its two operating modes (pre-mapped topic shortcuts vs. explicit ticker+slug pairing) and warns that pre-mapped topics often return compatibility warnings and are not guaranteed tradeable. It does not explicitly contrast with alternative sibling tools like polymarket_arbitrage, but it provides clear context for when the spread is meaningful and when it isn't.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about key listing behavior and scoping to an identifier, which adds value 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?

Three concise sentences: first gives core function, second provides use cases and examples, third describes scope and companion tools. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description explains return behavior (value vs list of keys), usage context, scoping, and related tools. For a simple read-only tool with one optional parameter, it is fully 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 the schema description already explains the 'key' parameter. The description reiterates the dual behavior (retrieve vs list) but does not add new semantic 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 verb 'retrieve' and the resource 'value previously saved via remember', and also lists all keys when omitted. It distinguishes itself from sibling tools by explicitly mentioning 'remember' and 'forget'.

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

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

Explicitly states when to use ('look up context the agent stored earlier... without re-deriving it from scratch'), implies when not to use (save with remember, delete with forget), and names alternatives ('Pair with remember to save, forget to delete').

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details: the mark_read flag modifies state (marking events read), and it explains the returned fields and filter capabilities, which go 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 long, front-loaded with the main action, and efficiently covers purpose, return data, filtering, and mark_read behavior without any redundant or filler content.

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

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

Despite lacking an output schema, the description explains what each event carries. It covers all filter options, the mark_read side-effect, and even mentions an alternative access method. For a read-only tool with 5 optional parameters, this is complete.

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

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

The schema already provides descriptions for all 5 parameters (100% coverage). The description adds context for type (example 'sec_8k'), since (ISO timestamp), and the effect of mark_read, but these are minor improvements. 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 it pulls fired events from a subscription feed. It specifies the return fields (source, citation_uri, raw payload) and distinguishes this tool from siblings like list_subscriptions and subscribe by focusing on reading alerts rather than managing 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?

The description advises that polling works fine and mentions an alternative REST endpoint for scripts/dashboards, providing some usage context. However, it does not explicitly state when not to use this tool vs. sibling tools, though the context makes it clear it's for reading alerts.

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

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

Annotations already mark it as read-only, open-world, idempotent, and non-destructive. Description adds fan-out behavior, source fallbacks, and soft-fail for USPTO patents.

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

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

Single paragraph is information-dense but well-organized with examples. Could be slightly more structured, but still concise for the amount of detail.

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

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

Despite no output schema, description explains return structure (changes grouped by source, total_changes count, citation URIs). Covers all key aspects for a 3-param tool.

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

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

Schema has 100% coverage. Description adds contextual examples for `since` (ISO/relative), explains `value` accepts ticker or CIK, and notes `type` is limited to 'company'.

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 provides a change feed for a company, listing SEC filings, news, and patents. Includes concrete query examples and distinguishes from sibling '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?

Explicitly tells when to use this tool vs. 'entity_profile', explains fallback from GDELT to GNews, and provides guidance on `since` parameter format.

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 significant context beyond annotations: explains scoping by identifier, persistence differences between authenticated and anonymous users, and idempotent nature. 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?

Four sentences, each serving a purpose: purpose, usage, scope/persistence, pairing. No wasted words, 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?

Simple tool with clear needs; description covers purpose, when to use, persistence, and relations to other tools. Complete for agent decision-making.

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 value by providing naming conventions (e.g., 'subject_property') and explaining value as 'any text'. Gives examples that aid semantics.

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

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

Description clearly states 'Save data the agent will need to reuse later' with specific verb (save) and resource (key-value pair). It distinguishes from sibling tools by mentioning recall and forget.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward' with examples. Also provides pairing instructions and notes on persistence (authenticated vs anonymous sessions).

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

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

Annotations already mark the tool read-only and idempotent, so the bar is lower. The description adds substantial behavior beyond annotations: non-equity instruments resolve, ambiguous matches return figi_candidates without asserting, unresolved identifiers are surfaced, GLEIF/OpenFIGI failures degrade gracefully, and internal cascading replaces multiple manual lookups.

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

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

The description is front-loaded with examples and the 'Use FIRST' directive, but the rest is a sprawling run-on wall of parentheticals and overlapping details. The content is valuable, but the structure makes it hard to parse and is far from 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 only two parameters and no output schema, the description is nearly exhaustive. It covers input variants, supported types, edge cases like ambiguous matches, unresolved identifiers, and degraded enrichment services, leaving little essential behavior undocumented.

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

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

Schema coverage is 100% for both parameters, but the description adds major value: accepted input forms (ticker, CIK, ISIN, or name), the exact-string-only caveat for bond issuers, and concrete examples for both company and drug types. The 'never pass the full noun phrase' guidance is especially important and not in the schema.

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

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

The description clearly states a specific operation: resolving a user-spoken name to canonical identifiers like CIK, ticker, LEI, FIGI, and RxCUI. The many query examples make the purpose unmistakable, but it never explicitly names or distinguishes itself from sibling tools like entity_profile or compare_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?

It gives an explicit trigger condition: 'Use FIRST whenever you have a name but need an ID.' The query examples and supported-type breakdown clarify common use cases, but the description does not explicitly say when not to use this tool or name alternative tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds that it probes with ai_visibility_check, ranks, and returns score/confidence/signal density. 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, front-loaded with action verb and resource, 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?

No output schema, but description fully explains return structure. All parameters mentioned, references sibling tool, explains process (probe, rank, surface). Complete for its function.

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

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

Schema coverage is 100%, baseline 3. Description adds value by clarifying first entity as 'subject' and explaining shared context disambiguates names, beyond schema descriptions.

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

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

Clearly states it compares AI visibility across multiple entities side-by-side, uses ai_visibility_check, and ranks results. Distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic).

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 says useful for competitive AI-marketing audits. Implies use when comparing multiple entities, but does not explicitly state when not to use or mention alternatives like single-entity check.

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

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

Discloses multiple behaviors: composite call, partial degradation with sources_failed list, and the 5-30 second delay for bundlephobia on new versions. The annotations already show readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, and the description adds complementary context without contradiction.

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

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

The description is moderately sized but packed with essential information. It is front-loaded with the core purpose and covers alternatives, partial failures, and environment details. Minor redundancy exists but does not detract significantly.

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 thoroughly explains the return structure (summary block, per-advisory detail, links, alternative versions). It also covers edge cases like partial failures and timeouts, making it nearly self-contained for correct 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?

Both parameters are fully covered by the input schema (100% coverage). The description adds useful context: scoped packages accepted for 'package' and defaulting to latest for 'version'. This exceeds the baseline of 3 by providing extra semantic guidance.

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 specifies exactly what the tool does: a composite check for npm packages covering license, advisories, version history, bundle size, dependency count, and ESM/tree-shake support. It clearly distinguishes from siblings by limiting to npm and mentioning alternative tools for other ecosystems.

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

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

Explicitly states when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also specifies when not to use: for PyPI/Maven/Cargo/Go it should fall under deps.dev:version directly.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds details on return fields and sort behavior, which is consistent and slightly extends transparency.

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

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

Concise and well-structured: purpose first, then filters, sort examples, and return fields. Every sentence adds value.

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

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

Given rich schema, annotations, and output schema, description covers all essential aspects completely. No gaps.

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

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

All 8 parameters are documented in schema with descriptions. Description adds concrete usage examples and explains sort options with real-world queries, going beyond schema.

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

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

Description clearly states it searches DataCite-registered DOIs for research outputs, listing specific filters and sort options. It distinguishes itself from sibling tools like 'get_doi'.

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

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

Provides explicit guidance on filtering (query, resource type, year, etc.) and sorting with examples. Lacks explicit 'when not to use' but context is clear.

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

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

Annotations already declare safety hints (readOnlyHint, idempotentHint). The description adds valuable behavioral details: embedding model (BGE-base-en), windowing (500-char overlapping), cap (200K chars with truncation flag), and output structure (offsets and similarity scores). 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 dense and informative, but slightly verbose as a single paragraph. It could be broken into shorter sentences for easier parsing. However, every sentence adds value.

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

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

Given the tool has 3 parameters, no output schema, and full schema coverage, the description provides complete information: algorithm, constraints, and usage context. The agent will know exactly how and when to use it.

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

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

Schema coverage is 100%, but the description adds context beyond field descriptions: embedding algorithm, window size, character limit, and example queries. It explains how the search works internally, which the schema does not.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples (SEC 10-K, article, tool result). It distinguishes itself from siblings like ask_pipeworx_grounded.

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

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

Explicitly says when to use: 'Use when the record is too big to cram into the prompt.' Provides a clear alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

The description discloses important behavioral traits such as requiring a Pipeworx OAuth account, SMS daily cap, webhook auto-disable after failures, and webhook signing. These go beyond the annotations (which indicate idempotent and non-destructive) and help the agent understand side effects and constraints.

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

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

The description is well-organized with clear sections for purpose, types, and delivery. It is somewhat long but every sentence adds value. Minor redundancy could be trimmed, but overall structure is effective.

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

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

The description covers all key aspects: core functionality, type-specific parameters, delivery channels with constraints, and authentication requirements. Given the complexity of the tool and lack of output schema, it provides sufficient context for correct invocation.

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

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

Schema coverage is 100%, but the description adds substantial meaning with detailed examples, required fields, format constraints, and webhook details. It explains the meaning of each type and param far beyond the schema's basic 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 creates a subscription to a live-data event stream and returns the id. It lists specific supported types and examples, differentiating 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?

The description implies when to use (to set up proactive monitoring) and provides context about required account type. It does not explicitly state when not to use or list alternatives, but the context is clear given the title and sibling tool names.

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, making the safety profile clear. The description adds that this is the 'onboarding entry point' and returns 'category-bucketed example questions', which provides 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?

The description is somewhat long but well-structured, starting with common user queries as triggers, then explaining the output and parameter usage. Every sentence adds value, though it could be slightly more concise without losing meaning.

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

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

Given the tool's role as an onboarding entry point and the rich annotations, the description covers purpose, usage, parameters, and output shape (category-bucketed examples with tool+argument shapes). No output schema exists, but the description adequately explains the return value.

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

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

Schema coverage is 100% with description for the one optional parameter. The description adds nuance: topic values like 'finance', 'pharma', etc., and explains behavior when omitted ('cross-category spread'), going beyond the schema's basic 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 explicitly states the tool returns 'category-bucketed example questions' with exact tool and argument shapes, serving as an onboarding entry point. It distinguishes from siblings like ask_pipeworx (which answers questions) and discover_tools (which lists tools).

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

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

The description provides clear guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to pass a topic vs no arguments, covering both use cases.

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

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

Annotations indicate non-read-only, non-destructive, idempotent. Description adds ownership enforcement, deactivation (not deletion), and link to recent_alerts, providing full behavioral context.

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

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

Two sentences, no unnecessary words, efficiently communicates key points.

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

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

Given the simple tool (one parameter, no output schema, annotations present), the description covers all necessary context: ownership, side effects, and relation to other tools.

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

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

The schema covers the single parameter 'id' fully with description. The description doesn't add additional parameter semantics beyond the schema.

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

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

The description clearly states the action 'Cancel a subscription by id' with the specific resource. It distinguishes from sibling tools like '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?

The description specifies ownership enforcement ('you can only cancel your own subscriptions') and explains the effect (deactivation not deletion, historical events remain via recent_alerts). It provides good context but doesn't explicitly mention when not to use or alternative tools.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds significant context by explaining the meaning of each verdict (especially the crucial distinction between could_not_verify and unsupported), the structured vs. grounded pipeline, and the presence of verification_error. Goes well beyond annotations and is not contradictory.

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?

Slightly verbose but well-structured: triggers, usage, pipeline, outputs, and important caveats. Every sentence contributes value, but the description could be trimmed without losing key information. Front-loaded with trigger phrases and clear purpose.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers the return verdict types, meaning, special error cases, citation format, and even explains the efficiency gain. It provides enough detail for an agent to know what to expect and how to interpret 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 is 100%, so baseline is 3. The description enhances tolerance_pct by explaining it overrides implied tolerances and suggests specific values (1–2) for hallucination detection, adding practical guidance beyond the schema. Claim parameter is inherently clear from the schema 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 explicitly states the tool's function with verbs like 'validate', 'fact check', 'verify' and a clear resource ('natural-language claim'). It distinguishes itself from siblings by explaining it performs end-to-end claim verification and replaces 4–6 sequential calls, setting it apart from simpler search or ask tools.

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

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

Provides explicit guidance on when to use ('Use whenever the agent needs to check whether something a user said is factually correct') and describes the routing behavior for financial vs. other claims, plus important semantics for verdicts. It effectively communicates usage context and differentiation from alternative tools.

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