Openbeautyfacts

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

Annotations already indicate safe, idempotent read. Description adds valuable context: default model is free, Anthropic requires BYO key, per-model response structure includes {score, confidence, signals, raw_response}. No contradictions.

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

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

Single paragraph, front-loaded with core action and result. Concise yet covers key details. Could benefit from slight structural separation (e.g., use cases vs. technical details).

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

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

No output schema, but description describes return fields. Covers all parameters and their purpose. Sufficient for agent to understand usage and results. Sibling list is diverse, but tool's niche is clear.

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

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

Schema coverage 100%, but description adds meaning: default model is free, _apiKey is for Anthropic and passes through directly, context helps disambiguate entity. Adds value beyond schema.

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

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

Description uses specific verb+resource: 'Probe one or more LLMs...score visibility (0-100) per model'. It clearly distinguishes from siblings by focusing on multi-model visibility scoring for brand/entity audits.

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 states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Provides context but does not explicitly exclude alternatives or compare to siblings like 'scan_competitor_ai_presence'.

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 establish read-only, open-world, and idempotent behavior; the description adds transparency about routing across many sources and returning citation URIs, without contradicting the annotations. It does not discuss failure modes or edge cases, but the annotation baseline lowers the bar.

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 verbose and repetitive, with repeated calls to 'PREFER OVER WEB SEARCH' and 'START HERE' and multiple example queries, making it longer than necessary. It is still organized around usage guidance, but could be more concise.

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

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

Given the tool's broad scope, lack of an output schema, and many sibling tools, the description adequately covers its role, routing behavior, relationship to alternatives, and news coverage, including citation URIs, so an agent understands when and how to invoke 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% and the description explains that all six parameters are aliases for the question field, provides natural-language examples, and clarifies the accepted aliases, adding meaning beyond the schema's bare field names.

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 routes questions to the appropriate source among 5,892 tools and 1,538 verified sources and returns structured answers with citation URIs, clearly distinguishing it from specialized siblings like ask_pipeworx_grounded and deep_research.

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

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

It provides explicit guidance to prefer this tool over web search, identifies it as the default starting point, and specifies when to use alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad or multi-part queries, plus news coverage details.

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

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

Annotations already cover read-only, idempotent, and open-world hints, and the description adds valuable context: the beta status, the possibility of candidate improvements being active, and the clarification that it is a fully working router. It does not contradict annotations and explains the experimental edge, which is beyond what structured fields convey. No significant gaps.

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

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

The description is informative and reasonably structured, starting with the beta label and then detailing current status and usage. It avoids excessive jargon, though phrases like 'Falls back to nothing' could be seen as slightly redundant. Overall, it is concise for the amount of context it conveys, with no wasted sentences.

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

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

The tool has no output schema, so the description partially compensates by referencing 'same response shape' as ask_pipeworx, which is a sibling tool. This is acceptable if the agent has access to that definition, but the description does not fully self-contain the core routing behavior or return format. Given the complexity and reliance on sibling context, it is adequate but not 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 description coverage is 100%, and all parameters are aliases for 'question' with clear descriptions. The description mentions 'same arguments' but adds no extra semantic meaning beyond what the schema provides. With full coverage, the baseline of 3 is appropriate; no additional parameter insight is given.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx, a universal router, and distinguishes it from the stable version by its experimental nature. It states it is 'identical' in functionality and scope, but does not explicitly define what the router does (e.g., routing questions to tools). This relies on prior knowledge of ask_pipeworx, making it somewhat dependent on sibling context, but still clear enough for differentiation.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' providing a clear condition for selection. It also notes that current behavior matches the stable router and that results are compared for merging. However, it does not explicitly state when NOT to use it (e.g., for stable, non-experimental results) or mention alternatives like ask_pipeworx_grounded. This is adequate but lacks explicit exclusions.

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

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

The description discloses key behavioral traits beyond annotations: it only extracts answers from tool results, returns verbatim evidence, and provides specific refusal reasons. It also mentions the extra LLM call cost, which is not captured by annotations.

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

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

Three sentences pack purpose, behavior, output shape, refusal reasons, and usage guidance without unnecessary fluff. The structure flows logically from mode to output to when-to-use.

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 though no output schema is provided, the description thoroughly details the success and refusal return shapes, including allowed refusal_reason values. It also gives domain examples and explicitly contrasts with ask_pipeworx, making the tool self-contained.

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

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

The schema already fully covers all six parameters, including aliases and the required question parameter. The tool description does not add parameter-specific guidance beyond what the schema provides, so the neutral baseline 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?

Clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, naming the specific verb 'extract' and the resource. It also distinguishes itself from ask_pipeworx by emphasizing grounded answers and refusal behavior.

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 the tool: for high-stakes reads, or whenever an answer will be quoted, cited, or acted on, and when the agent must not invent facts. It also explicitly says to prefer ask_pipeworx for casual lookups, providing a clear alternative.

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

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

The description provides extensive behavioral details beyond annotations, including market resolution, classification, fan-out logic, response shapes, resolver contract with match confidence, parent event extraction, news fallback handling, safety short-circuits for low-confidence and closed markets, wide-spread warnings, and cancellation rule parsing. No contradiction with annotations (readOnly, idempotent, openWorld, non-destructive).

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 section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and uses bullet-like formatting. Every sentence adds value, though a slightly more concise summary might help quick scanning. Still, it is effective and not tautological.

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

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

Given the tool's complexity (multiple input types, fan-out to various data sources, rich response), the description covers all essential aspects: input handling, output structure, edge cases (low confidence, closed markets, wide spreads), cancellation rules, and practical usage advice. No output schema exists, but the description compensates fully.

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 value by explaining how parameters affect behavior (e.g., depth 'quick' vs 'thorough', include_raw false keeps responses under ~20KB, true for full payloads), and provides examples for the 'market' parameter. This goes 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 it researches a Polymarket bet by pulling Pipeworx data, with specific input types (slug, URL, question text) and output (evidence packet + comparison). It provides usage examples and classifier categories, making the tool's purpose highly specific and distinguishable from the broad set of sibling tools.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', giving clear usage scenarios. While it doesn't explicitly state when not to use or name alternatives, the context is sufficient for an agent to decide applicability.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds that it makes a single parallel call, handles fiscal year differences, returns sorted results with citation URIs, and discloses data sources (SEC EDGAR/XBRL, FAERS). No contradictions.

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

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

The description is a single focused paragraph that first gives natural language triggers, then purpose, then details. No wasted sentences; front-loaded and efficient.

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

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

Despite no output schema, the description explains the return format: paired data sorted by primary metric, with citation URIs per entity. It covers all important aspects of tool usage and behavior.

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

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

Schema coverage is 100%, but description adds rich meaning: for type, it specifies what data is pulled (financials vs regulatory); for values, it gives allowable formats (tickers/CIKs for company, names for drug) and constraints (min 2, max 5).

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs. It provides example natural language queries and differentiates from sibling tools like entity_profile by emphasizing multi-entity comparison.

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

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

Explicitly instructs to always prefer this tool over sequential single-pack lookups when comparing entities, and states it replaces 8-15 lookups. Also explains the context for each type (company vs drug).

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses important behavioral details: account/payment requirements, latency expectations, hop-based iteration, contradiction scanning, semantic excerpting, and that citation_uri is only present when fetchable. This significantly enriches the agent's understanding of side effects and return characteristics.

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

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

The description is front-loaded with the core purpose and key differentiators, but it is quite verbose and contains redundant phrases (e.g., 'IN PARALLEL', 'never invented', 'gap recovery') repeated across segments. Trimming would improve readability without losing essential details.

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

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

There is no output schema, so the description compensates by thoroughly explaining the return packet: findings with verbatim evidence, confidence, source, fetched_at, hop field, citation_uri, gaps[], and contradictions[] (for standard/thorough). It also covers latency, excerpting behavior, and account prerequisites, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the depth semantics already present in the schema (quick=3, standard=3 with gap recovery, thorough=6 paid) without adding new parameter meaning, though it does reinforce that broad/multi-part questions are acceptable.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1538 STRUCTURED data sources' that 'decomposes your question into focused facets' and returns a findings packet. It explicitly distinguishes itself from ask_pipeworx for news/search use cases, so an agent can readily identify when deep_research is the intended tool.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: best for 'broad/multi-part questions over structured data', while 'for a single lookup use ask_pipeworx' and for breaking news topics 'prefer ask_pipeworx'. It also explains depth-level selection and second-hop iteration, leaving no ambiguity about when to choose this tool over siblings.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds that results include 'full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed.' It also notes 'top-N most relevant' ranking. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and uses efficient listing of categories. However, it is slightly verbose with the list of examples and could be trimmed without losing clarity.

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

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

Given the tool's simplicity (read-only, idempotent discovery) and full schema coverage, the description is fairly complete. It lacks explicit explanation of the return structure, but since there is no output schema, this is acceptable.

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 detailed parameter descriptions. The description adds value by listing aliases (task, q, description, search) for query and providing concrete examples like 'look up FDA drug approvals' and 'analyze housing market trends'.

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: 'Find tools by describing the data or task.' It lists specific categories (SEC filings, FDA drugs, etc.) and explains that it returns top-N relevant tools with full schemas. This distinguishes it from sibling tools which are data-focused.

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

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

The description explicitly advises when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It provides context but does not mention specific exclusions or alternatives.

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

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

Annotations already mark it read-only/idempotent, and the description adds substantial non-obvious behavior: partial success surfaced via `sources_used`/`sources_failed`, an empty section being 'a real no-data, not a bug', private companies returning resolved:false with a notes line instead of failing, an expected-empty case for small-molecule drugmakers, and the GDELT-to-GNews fallback. These materially change how an agent should interpret results, and nothing contradicts the annotations.

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

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

The description is front-loaded with trigger phrases and core purpose, and nearly every sentence carries useful information. However, it is one dense run-on paragraph, and the returns enumeration contains a visibly garbled/duplicated fragment that repeats the source list ('patents (USPTO), federal contracts (USAspending)...') mid-sentence, which disrupts 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?

For a high-complexity tool with no output schema, the description covers inputs, identity resolution, major return groups (cik, recent_filings with pipeworx URIs, fundamentals, per-source sections), and edge cases (private companies, expected-empty sections, partial source failure). The garbled middle section leaves the exact names of per-source result keys slightly unclear, which prevents a higher score.

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

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

Schema coverage is 100% and the schema already documents the accepted value shapes, concrete examples ('AAPL', '0000320193', 'Moderna'), and the type/value interchangeability, so the description adds little at the parameter level. Its extra context (resolved_from/resolved_to, private-company resolved:false) concerns return behavior rather than argument construction, so the baseline of 3 with the schema doing the heavy lifting 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?

States a specific function — 'full cross-source profile of a US public company in ONE parallel call' — backed by concrete trigger phrases ('brief me on Tesla', 'company profile for Microsoft', 'everything you know about $TICKER'). The multi-source fan-out (SEC EDGAR, XBRL, USPTO, USAspending, Purple Book, DOL LCA, news, GLEIF) clearly separates it from single-purpose lookups and chained calls.

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

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

Gives an explicit preference rule — 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' — plus invocation examples an agent can match to user intent. It stops short of naming sibling alternatives (e.g., compare_entities, resolve_entity) or stating when NOT to use this tool, so exclusionary guidance is incomplete.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and pairing with related tools, but does not contradict annotations.

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

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

Two sentences with no waste. The first sentence states the action, the second adds usage guidance. Front-loaded and efficient.

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

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

Given the tool's simplicity (1 param, no output schema) and the annotations, the description fully covers purpose, usage, and lifecycle context. 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?

Schema already describes the 'key' parameter as 'Memory key to delete' (100% coverage). Description adds no further meaning beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key', which is a specific verb+resource. It explicitly distinguishes from sibling tools by mentioning 'Pair with 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?

Provides explicit when-to-use conditions: 'when context is stale, the task is done, or you want to clear sensitive data'. Also names alternatives (remember, recall) for context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', and notes output destination. 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?

Description is concise, with main purpose in first sentence, followed by process and use cases. Could be slightly more compact but overall well-structured and efficient.

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

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

Given no output schema, the description adequately explains the output format ('standard llms.txt markdown format', 'single text blob'). Covers key behavior for a simple tool with 2 parameters.

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

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

Schema coverage is 100%, so baseline 3. The description does not add significant meaning beyond the schema descriptions for 'url' and 'max_links' (e.g., default values mentioned).

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 generates a 'production-ready llms.txt file for any URL', specifying the resource and action. It distinguishes from sibling tools by focusing specifically on llms.txt 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 provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), but does not mention when not to use or compare directly to sibling 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?

The description adds value beyond annotations by listing the specific fields returned (name, brand, categories, ingredients, etc.). Annotations already indicate it is read-only, non-destructive, and idempotent; no contradiction.

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

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

The description is two sentences plus an example, front-loaded with the action and source. Every sentence adds value with no redundancy.

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

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

For a single-parameter lookup tool with rich annotations and no output schema, the description adequately covers what data is returned. 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?

The schema has 100% coverage and describes the barcode parameter. The description adds example barcodes but does not provide additional semantic meaning beyond the schema.

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

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

The description clearly states the tool is for beauty product barcode lookup, specifying the source (Open Beauty Facts) and the data returned (name, brand, categories, ingredients, etc.). It distinguishes itself from siblings like 'search_products' which likely does text-based search.

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

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

The description provides a clear use case (barcode lookup) and an example, but does not explicitly state when not to use it or mention alternative tools for similar tasks.

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, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing the return fields (id, type, params, created_at, etc.) and the default behavior of listing only active subscriptions with an optional include_inactive parameter. No contradictions with annotations.

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

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

Two sentences: first states the action, second provides usage guidance. Every sentence adds value, and the description is front-loaded with the main purpose. No unnecessary words.

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

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

Despite no output schema, the description lists the key return fields (id, type, params, created_at, last_fired_at, fire_count) and explains when to use the tool. For a simple list operation with one optional parameter, this is complete and sufficient.

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

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

The input schema has one parameter (include_inactive) with full description coverage (100%). The description does not add any additional meaning beyond the schema; it only mentions the return fields. Baseline 3 is appropriate since schema covers the parameter adequately.

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 'List the caller's active subscriptions.' It clearly identifies the verb (list), resource (subscriptions), and scope (caller's active). Although it does not explicitly differentiate from sibling tools like subscribe or unsubscribe, the purpose is unambiguous and 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 advises using this tool to 'review what you're monitoring before adding more or to find an id to cancel.' This provides context for when to use it, but it does not explicitly mention when not to use it or suggest alternative tools. Sibling tools exist (e.g., subscribe, unsubscribe), but the guidance is implicit.

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

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

Annotations provide no safety hints (all false), so the description carries the full burden. It richly discloses behavioral traits: anonymous filing returns a claim_token, passing that token later reads resolution status, rate-limited to 5/day, free and doesn't count against quota, daily review. 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, use-cases, exclusion scope, message guidance, token mechanics, rate limits. The most critical facts are front-loaded in the first two sentences, making it efficient despite its length.

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

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

For a feedback tool with no output schema and 4 optional parameters, the description fully covers when to use, what to include, how the claim_token works, and operational limits. No important aspect is left unexplained.

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 beyond the schema by explaining the claim_token round-trip flow in prose and instructing message content ('don't paste the end-user's prompt, describe issue in terms of Pipeworx tools/packs'). This elevates it above the baseline.

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

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

The description opens with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly scopes the tool to feedback about Pipeworx tools/packs and distinguishes it from all sibling tools (research, search, subscription tools) by being the only feedback mechanism.

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

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

Explicitly states when to use ('Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)') and when NOT to use ('if the tool came from a different MCP server... file it with that server instead'). Also clarifies how to identify Pipeworx tools.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds context: data is derived from CF analytics-engine, contains no PII, and is cached with varying refresh intervals (5min-1h). No contradiction with annotations.

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

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

The description is concise (3 sentences plus bullet points) and well-structured. It front-loads the primary return value, follows with use cases, and ends with technical details. Every sentence adds value with no redundancy.

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

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

For a tool with one optional parameter and no output schema, the description covers all needed context: return structure, data source, privacy, caching, and use cases. It is self-contained and fully informative.

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 single parameter 'window' has 100% schema coverage with enum values. The description adds meaningful guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides operational 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 it returns 'top tools, top packs, and total call volume' over recent windows. It distinguishes from sibling tools by focusing on usage trends of other AI agents, not on direct data retrieval or entity profiles.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. While it doesn't state when not to use it, these guidelines provide clear context for appropriate usage relative to siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description goes far beyond by detailing monotonicity checks, partition-sum validation, Jaccard similarity filtering, placeholders filtering, and fill checks against live order book depth. It warns about false signals when realizable edge is non-positive. No contradiction with annotations.

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

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

The description is lengthy but well-structured with paragraphs, bold terms, and clear sections. Each sentence contributes unique information about modes, filters, or response format. Slightly verbose but not redundant or wasteful.

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

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

Despite lacking an output schema, the description fully documents the response structure: opportunities array with gap_pp, suggested_trade, reasoning, context, and in event mode a partition_check object. It also explains fill check conditions and when not to trade. All relevant behavioral details are covered for a tool of this complexity.

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

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

Schema coverage is 100% and each parameter has a description. However, the tool description significantly enriches parameter meaning by explaining how event and topic affect the scanning behavior, providing examples, and detailing the output differences. This adds substantial value beyond the schema.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks on Polymarket. It explicitly distinguishes between three modes: no args (trending scan), event (single event), and topic (cross-event), making the purpose very specific and differentiated from sibling tools.

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

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

The description provides explicit guidance on when to use each mode and when not to: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also advises against trading when the fill check indicates no realizable edge and directs to polymarket_fill_risk for custom sizing, effectively covering exclusions and alternatives.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by explaining caching behavior (1h at KV level), response structure with diagnostics, handling of Fed bets, and edge calculation details. 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 lengthy but well-structured: purpose first, then segments, opportunity details, knobs, and response format. While it packs a lot of information, every sentence adds value. Slightly verbose but appropriate for the complexity.

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

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

With no output schema, the description thoroughly explains the response structure (by_segment, diagnostics, fed_candidates), opportunity fields (edge_pp_net, kelly_fraction, etc.), and all filters. It covers caching and error cases (why a segment is empty).

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context for knobs like min_liquidity, max_spread_pp, and slippage_pp with practical examples and reasoning, enhancing understanding beyond the schema descriptions.

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

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

The description explicitly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, targeting the 'what should I bet on today' use case. It details three model families and distinguishes the tool from potential siblings by its specific functionality and output grouping.

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 the tool (discovering betting opportunities without paging markets) and explains the tradeable-edge knobs for filtering. However, it does not explicitly state when not to use it or mention alternative sibling tools for comparison.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and not destructive. The description adds significant behavioral details: response structure (tracked, expired, snapshot_dates), computed fields (trend, decay_pp_per_day, lifespan_days), and limits (60-day snapshot TTL, decay from daily closes).

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

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

The description is front-loaded with the core purpose and structured into sections for response fields and limits. While somewhat lengthy, all sentences are informative and necessary for understanding the complex output.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and their fields. It also covers limitations and runtime behavior (gaps in snapshots, TTL). No required parameters, so default behavior is clear.

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

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

The input schema covers both parameters with descriptions; schema description coverage is 100%. The description adds clarity by specifying defaults (days=14, window='1wk') and constraints (clamp 2-30, max 30), enhancing the schema information.

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 providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself by answering specific questions about edge duration and trend, which is distinct from sibling tools like polymarket_edges for current edges.

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

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

The description explains when to use the tool (e.g., comparing fresh vs old edges) through concrete examples. It implies context for usage but does not explicitly state when not to use it or list alternative tools beyond the example.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds significant behavioral context: walking the ladder, returning verdicts (clean/degraded/cannot_fill), per-leg fill details, thin_legs detection, forced_directional_risk naming, and warnings about partial fill risks. No contradiction with annotations.

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

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

The description is well-structured with clear sections and front-loaded purpose. It is dense but efficient for the complexity. Minor reduction in score due to length, but every sentence adds value.

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

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

Given no output schema, the description thoroughly explains return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk for basket). It also covers edge cases and risks, making the tool fully understandable.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds extra meaning: explains the auto default for basket side, interprets size_usd differently for single-market vs basket, and notes the clamp range. This goes beyond the schema's basic parameter descriptions.

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

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

The description clearly states the tool's purpose as a realizable-vs-theoretical edge check against live CLOB order-book depth. It details two distinct modes (single-market and basket) with specific verbs and resources. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by providing explicit usage guidance.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when not to use (partial basket fills can lead to unhedged positions) and mentions alternatives by referencing sibling 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 indicate readOnly and idempotent behavior, and the description adds substantial behavioral context: it explains matching methodology, compatibility warnings, skipped-category counters, the meaning of null in temporal_alignment, gross-vs-net fee treatment, and the disclosure that Kalshi fees are not modeled. It also explicitly warns that compatibility codes may be non-empty even when matched_pairs > 0, which prevents misinterpretation of the response. No contradiction with annotations exists.

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

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

The description is long but well-structured with uppercase section labels (TWO MODES, RESPONSE, SAFETY FIELDS) that make it scannable. Every sentence contributes meaningful operational detail. It could be trimmed slightly, especially the extensive enumeration of codes, but the density serves an inherently complex cross-venue comparison tool.

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

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

With no output schema, the description carries the full burden of explaining the response — and it does: venue leg prices, spread top_spreads_pp, compatibility_warning/codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters are all described. It also covers the meaning of null and the never-pair 'unknown' rule. Given the tool's complexity, this is complete enough for an agent to call and interpret 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 baseline is 3. The description adds value beyond the schema by stating that both modes run the identical token-overlap matcher, that topic mode auto-fetches the matching event on each venue, and that explicit parameters override the topic-mapped side. This clarifies parameter interactions not fully detailed in the schema alone.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly identifies both the resource (the spread) and the two venues involved. It further distinguishes this tool from Polymarket-only siblings by explicitly naming both Kalshi and Polymarket, and the two modes ('topic' and explicit ticker/slug) make its scope unmistakable.

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

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

The description provides explicit guidance on the two modes and when to use each: topic shortcuts for pre-mapped macro events and explicit ticker/slug pairs for custom comparisons. It also cautions that pre-mapped topics often return compatibility warnings and are not necessarily tradeable, giving useful when-not-to-trust guidance. It stops short of naming alternatives among siblings, but the context is sufficient for an agent to decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: scoping to the user's identifier (anonymous IP, BYO key hash, or account ID) and the ability to list all keys by omitting the argument. No contradictions.

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

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

Three sentences, no wasted words. Front-loaded with the core function, then use cases, then scoping and pairing. Every sentence adds unique 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?

No output schema, so description should hint at return format. It says 'retrieve a value' and 'list all saved keys', but doesn't explicitly describe the returned structure (e.g., key-value pair or array of keys). Still adequate for a simple tool and includes scoping and pairing 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%, so baseline is 3. The description adds meaning beyond the schema by explaining that omitting the 'key' parameter lists all keys, and provides usage examples (ticker, address, notes). This practical context justifies a 4.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys when no key is provided. It uses specific verbs and resources (retrieve, list keys) and differentiates from siblings like 'remember' and 'forget' by naming them. Examples (ticker, address, notes) add clarity.

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

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

The description explicitly says when to use ('look up context stored earlier... without re-deriving') and how to list keys (omit key argument). It implicitly distinguishes from 'remember' (save) and 'forget' (delete), but does not explicitly state when not to use or name alternative tools beyond these siblings.

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

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

The description discloses that mark_read:true modifies the feed state (flags events read), which contradicts the annotation readOnlyHint: true. According to the rules, a score of 1 is given when the description contradicts annotations. Annotation contradiction is flagged.

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 concise paragraph that front-loads the main purpose and then elaborates on key details. Every sentence adds value with no redundancy, making it efficient and well-structured.

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

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

The description covers the main functionality (retrieval, filtering, mark_read behavior), explains return fields (source, citation_uri, raw payload), and provides an alternative access method. Given no output schema, it adequately addresses the tool's 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?

The description adds value beyond the schema by providing examples for 'type' (e.g., 'sec_8k'), clarifying that 'since' is an ISO timestamp, and explaining the effect of 'mark_read'. With 100% schema coverage, the description enriches the parameter semantics.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed', and explains what each alert carries. However, it does not explicitly differentiate from sibling tools like recent_changes or list_subscriptions, though the context is sufficiently distinct.

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 some usage guidance, noting that polls work fine and offering an alternative URL. However, it lacks explicit when-to-use or when-not-to-use instructions compared to other tools, and does not cover prerequisites or exclusions.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds cross-source fan-out, news fallback logic (GDELT→GNews), and soft-fail for USPTO due to API sunset. Good 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?

Single paragraph with all key info. No fluff, but lacks structural breaks (e.g., bullet points). Still highly efficient.

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

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

Coverage of complexity: describes sources, fallback, soft-failures, and output format (structured changes[] grouped by source, count, citation URIs). No gaps given no output schema.

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

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

Schema coverage is 100% with descriptions. The description adds meaning: clarifies `since` formats (ISO date or relative shorthand) and gives examples ('30d', '1m' for typical monitoring). Also explains `value` accepts ticker or CIK.

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 provides a change feed for a company (SEC filings, news, patents) in a time window. It distinguishes from sibling `entity_profile` which provides static profiles.

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

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

Explicit use cases and example queries are given. It recommends using `entity_profile` for static profiles. However, it doesn't explicitly state when not to use this tool (e.g., for real-time data).

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

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

Annotations provide idempotentHint=true and destructiveHint=false, but the description adds essential context: scoped by identifier, persistence differences between authenticated (permanent) and anonymous (24 hours). 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 succinct sentences, each contributing value: core purpose, usage context, storage details, and companion tools. No fluff; front-loaded with the main action.

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 memory tool with two parameters and no output schema, the description covers purpose, when to use, storage behavior, scoping, and persistence. Referencing recall and forget completes the mental model.

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 descriptions already cover both key and value. The description adds value by giving examples of key patterns (e.g., 'subject_property', 'target_ticker') and clarifies that value can be any text, augmenting 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 (Save) and resource (data to reuse later), and distinguishes from siblings by mentioning paired tools recall and forget. Examples of what to store (ticker, address, preference) make it highly 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?

Explicitly states when to use (discover something worth carrying forward) and provides concrete scenarios. It also mentions companion tools for retrieval and deletion, guiding the agent on workflow.

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

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

Even with readOnly/idempotent hints already present, the description adds substantial behavior: it cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI is unavailable, returns figi_candidates when ambiguous, labels every identifier by source, and reports unresolved ones explicitly. This is far beyond what annotations convey.

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

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

The description is long and dense, but nearly every clause adds operational value, from supported types to graceful degradation. The structure with SUPPORTED TYPES and explicit examples helps navigation. It slightly over-elaborates in the company parenthetical, but not wastefully.

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

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

With no output schema, the description carries the burden of explaining what the agent gets back, and it does: identifiers by source, unresolved flag, figi_candidates for ambiguous names, and RxNorm citation. Given the tool's internal complexity and lack of output schema, this is complete enough for an agent to invoke it correctly.

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

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

The schema already documents both parameters well, and the value parameter description is detailed. The tool description adds domain-level meaning: accepted formats (ticker, CIK, ISIN, brand/generic name), the ISIN-to-LEI mapping behavior, and the warning to pass only the entity name, not the full noun phrase. This compensates beyond the schema baseline.

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

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

The description opens with concrete user utterances, states the exact verb-resource pair ('resolve a user-spoken NAME to the canonical/official identifiers'), and enumerates supported entity types. This makes the tool's role unmistakable and distinct from siblings like entity_profile or validate_claim.

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

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

It gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also clarifies edge cases like non-equity instruments and ambiguous matches. It does not name alternative sibling tools for exclusions, but the usage context 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, fully covering safety and idempotency. The description adds valuable behavioral context: it calls ai_visibility_check per entity, ranks results, and returns a structured list with score, confidence, and signal density. No contradictions.

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

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

The description is three sentences: purpose, process, and use case. Every sentence adds distinct value. It is front-loaded with the core action and avoids redundancy with the schema or annotations.

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

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

For a tool with 4 parameters and no output schema, the description adequately covers inputs, process, and output structure (ranked list with score/confidence/signal density). Minor gap: it does not explain how confidence or signal density should be interpreted, but given the tool's simplicity, this is acceptable.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds critical semantic meaning: the first entity is treated as the 'subject' for narrative, while others are competitors. It also clarifies that context is shared across all probes and that models and _apiKey control which AI models are used.

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 'Compare AI visibility across multiple entities side-by-side' with a specific verb and resource. It distinguishes from sibling 'ai_visibility_check' by noting it probes multiple entities and ranks them, and from 'compare_entities' by specifying the AI visibility domain.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and a concrete example question. It implicitly suggests when to use (comparative analysis) but does not explicitly exclude single-entity use or mention alternatives like 'ai_visibility_check'.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint false) are provided. The description adds details: fans out across deps.dev and bundlephobia, mentions partial failures, timing issue (first measurement 5-30s), and sources_failed list. 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?

Description is somewhat long but well-structured: starts with summary, then usage guidance, output details, and caveats. Every sentence adds value, but could be slightly more concise.

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

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

Given complexity (composite, multiple sources) and no output schema, the description provides detailed return fields, error handling, and timing caveats. Completely adequate for agent selection and invocation.

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

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

Schema coverage is 100% with clear descriptions. The description adds context: scoped packages accepted, version defaults to latest. This adds value beyond schema.

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

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

The description clearly states it's a composite check for npm packages covering license, advisories, version history, and bundle size. It specifies the verb 'scan' and resource 'dependency', and distinguishes from siblings (e.g., scan_competitor_ai_presence) by focusing on npm packages.

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 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also notes NPM only in v1 and directs to deps.dev for other ecosystems, providing clear when-to-use and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds return field details (barcode, name, brand, categories, image) but does not contradict annotations.

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

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

Two sentences plus an example. Front-loaded with purpose and no unnecessary words. Every sentence adds value.

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

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

Given no output schema, description explains return fields. Covers main use case but omits pagination or error details. Adequate for a simple search tool.

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

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

Schema coverage is 100%, so parameters are already documented. Description adds examples but no new semantic information beyond what schema provides. Baseline 3.

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

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

The description clearly states the verb 'search' and the resource 'cosmetics and personal care products' in 'Open Beauty Facts'. It further specifies return fields and gives examples, distinguishing it from sibling tools like get_product.

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 context for when to use (finding ingredients/details of personal care items) but does not explicitly state when not to use or mention alternatives among siblings.

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

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

Annotations already indicate readOnly, idempotent, etc., and description adds behavioral details: truncation at 200K chars flagged, BGE-base-en embeddings, cosine over 500-char windows. 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?

Description is a paragraph, but each sentence adds distinct value. Front-loaded with primary action, then details. Slightly verbose, no waste.

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

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

For a tool with no output schema, description is complete: explains return structure (passages with offsets and scores), mentions size cap, pairing with another tool. Covers all key 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%, but description adds value: clarifies 'text' is document text max 200K chars, 'limit' default 5, 'query' is natural-language with examples. Not merely repeating 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 does semantic search inside a fetched record, returning top-N passages with character offsets and similarity scores. It distinguishes from sibling tools by mentioning it pairs with ask_pipeworx_grounded.

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

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

Explicitly says to use when record is too big for prompt to save context, and suggests pairing with ask_pipeworx_grounded. No explicit when-not, 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?

Adds rich behavioral details beyond annotations: OAuth requirement, delivery channel specifics, SMS rate cap, webhook auto-disable, signing secret one-time return. 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?

Long but efficient: front-loaded with purpose, then prerequisites, types, delivery. Every sentence adds value. No fluff or repetition.

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

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

Comprehensive: describes what it does, what it returns, constraints, edge cases (webhook failures, phone verification). No output schema, but return value is explained. Covers all aspects given 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%, but description adds significant meaning: explains each type with examples, details delivery options, verification requirements, and constraints like SMS cap. Adds value beyond schema.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' Specific verb+resource. Distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides clear context: requires Pipeworx OAuth account, lists supported types and delivery options. Does not explicitly say when not to use, but context implies it's for persistent monitoring, not one-off queries.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations: it returns category-bucketed example questions drawn from a live catalog, and explains the tool's role as an onboarding entry point.

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 common user queries and clearly states the purpose. It is informative but could be slightly more concise; however, every sentence adds value, so it earns a high 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 there is no output schema, the description fully explains what is returned (category-bucketed example questions with tool+argument shapes) and how to use the optional parameter. It is complete for a simple onboarding tool.

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

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

Schema coverage is 100%, so the schema already documents the 'topic' parameter. The description adds example values ('finance', 'pharma', etc.) and usage guidance ('Omit for a cross-category spread'), which adds marginal value but doesn't fundamentally change 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: returning category-bucketed example questions as an onboarding entry point. It uses specific verb 'returns' and describes the resource. It distinguishes itself from siblings like ask_pipeworx by positioning as a first-use tool.

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

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

Explicitly states when to use this tool ('Use this FIRST when you do not yet know what Pipeworx can do for you') and how to call it (no arguments for full spread, topic for focus). It also mentions alternatives like meta-tools, providing clear 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 indicate non-readOnly, idempotent, and non-destructive. The description adds valuable context: ownership is enforced, the row is deactivated (not deleted), and historical events remain accessible via recent_alerts. 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?

Two sentences with no wasted words. The action is front-loaded, and key behavioral details are included efficiently.

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

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

Given the single parameter and no output schema, the description covers purpose, ownership, and side effects. It could mention the response or that it's idempotent, but annotations cover that. Overall quite 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 description for 'id' is adequate ('Subscription id (uuid) returned by subscribe'), and schema coverage is 100%. The description does not add extra meaning beyond what schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id', specifying the verb and resource. It differentiates from sibling tools like 'subscribe' and 'list_subscriptions' by describing the action as cancellation and ownership enforcement.

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

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

The description implies usage for canceling a subscription and mentions ownership enforcement, but does not explicitly state when not to use it or provide alternatives beyond the implicit sibling context.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, but the description adds crucial context beyond that: the dual-path routing logic, the semantic distinction between could_not_verify and unsupported, and a warning that could_not_verify carries a verification_error and must not be treated as evidence. It also notes that the tool replaces multiple sequential calls, which is a significant behavioral trait not inferable from annotations.

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

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

The description is well-structured and information-dense. It opens with natural-language examples, then clearly states the purpose, describes the two routing paths, lists the return values, and covers error semantics. Every sentence earns its place, and the length is justified by the tool's complexity.

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

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

Despite lacking an output schema, the description fully explains the tool's behavior, including all possible verdict values, the meaning of could_not_verify vs unsupported, and the tolerance_pct override semantics. It addresses key edge cases like hallucination detection and error handling, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving a concrete example for claim and by providing practical guidance on tolerance_pct (e.g., set 1–2 for hallucination detection) and explaining the default and cap behavior, reinforcing and extending 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 that validate_claim performs natural-language claim verification against authoritative sources, using explicit verbs like 'verify' and 'fact check'. It distinguishes itself from sibling tools by naming two specific execution paths (structured SEC EDGAR for company-financial claims, grounded pipeline for all others) and by noting it replaces 4–6 sequential calls. This gives a specific verb, resource, and scope while setting it apart from generic ask/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 gives strong usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct,' and it explains when the fast structured path applies versus the grounded fallback. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it falls just short of a full 5.

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