Fda Devices

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

The description discloses behavioral traits beyond annotations: default model is Workers AI Llama-3.3-70b (free), Anthropic requires a BYO key and incurs direct costs, and it returns per-model results plus a combined view. Annotations already indicate readOnlyHint, idempotentHint, etc., and the description adds operational context without contradiction.

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

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

The description is concise (two sentences plus a brief list for return structure) and front-loaded with the primary action and default behavior. Every sentence serves a purpose: explaining the tool, how to extend it, and what results to expect. No unnecessary words.

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

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

Given the tool's complexity (4 parameters, no output schema), the description provides sufficient information: it describes the return schema (per-model objects with score, confidence, signals, raw_response plus combined view), default model, and optional parameters. No output schema exists, so the description adequately compensates. The agent has enough context to select and invoke the tool correctly.

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

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

The input schema has 100% description coverage for all four parameters. The tool description adds value by explaining the role of each parameter in context: `entity` is the thing to ask about, `models` lists which to probe, `_apiKey` is optional for Anthropic, `context` helps disambiguate. This exceeds the baseline of 3 for high coverage, earning 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 uses specific verbs ('probe', 'score') and identifies the resource ('LLMs for what they know about a business / brand / product / topic'). It clearly distinguishes from sibling tools like 'ask_pipeworx' which likely answer questions rather than score visibility. The return structure (score, confidence, signals per model) further clarifies the tool's purpose.

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

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

The description explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also provides guidance on optional parameters (e.g., `_apiKey` required for Anthropic, `context` for disambiguation). While it doesn't explicitly state when not to use, the context of sibling tools implies alternative functions. A score of 4 reflects clear, actionable guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint true, and destructiveHint false. The description adds valuable behavioral context: routing to over 5,000 tools, returning structured answers with stable citation URIs, being fast (one call), and working on all tiers. This goes beyond annotations to inform the agent of internal routing and output format.

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

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

The description is relatively long but well-structured. It front-loads the key recommendation ('PREFER OVER WEB SEARCH'), then systematically covers scope, usage guidelines, and alternatives. Every sentence serves a purpose, though some redundancy exists (e.g., listing of domains). It is efficient for its content density.

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

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

Given the tool's broad scope (routing to many sub-tools) and simple input schema, the description provides sufficient context: it explains the tool acts as a router, describes the output (structured answer with citations), gives example queries, and mentions tier compatibility. The lack of an output schema is partly compensated by the description of citation URIs.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing extensive examples of what constitutes a good question (e.g., 'current US unemployment rate', 'Apple's latest 10-K'), which helps the agent formulate proper inputs. However, it doesn't add new parameter-level semantics beyond the schema.

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

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

The description clearly states the tool's purpose: to answer factual questions about structured data by routing queries to a vast library of tools. It explicitly distinguishes from sibling tools like ask_pipeworx_grounded and deep_research, making the purpose and scope unambiguous.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It recommends using this tool as the default entry point for most questions, and specifically names alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part queries). It also gives concrete examples of appropriate 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: it's a full working router, currently matches ask_pipeworx exactly, and is used for A/B testing candidate improvements. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with the key point (beta version). Each sentence adds relevant information, though slightly verbose. Could be more concise but remains clear.

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 references that the response shape is identical to ask_pipeworx, which is sufficient. It explains current status, usage, and comparison. Mostly complete for a router tool with a well-known sibling.

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 mentions 'same arguments' but adds no parameter-specific meaning beyond what the schema already provides (all aliases for question). No new semantic value added.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router for 5,211 tools. It distinguishes itself from the stable sibling ask_pipeworx by highlighting its experimental nature with candidate routing improvements.

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

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

The description explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and mentions results are compared against the stable router. It does not explicitly state when not to use it, but the context implies it for experimental purposes, which is adequate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds return format with refusal reasons and cost (one extra LLM call). No contradiction, and provides significant behavioral context beyond annotations.

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

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

Front-loaded with core purpose, then provides necessary details. Slightly verbose but each sentence adds value. Good structure for a complex tool.

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

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

Comprehensive: covers return format, refusal reasons, cost tradeoff, use cases, and how data is sourced. No output schema, so description fully explains return values. Completes the picture for a grounded answer tool.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question.' Description does not add meaning beyond what schema provides. Baseline 3 is appropriate as schema carries the burden.

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

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

Clearly states it is a hallucination-resistant answer mode for high-stakes reads. Distinguishes from sibling 'ask_pipeworx' by noting extra cost and preference for casual lookups. Verb+resource is specific: answer grounded questions.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and lists example domains. Also states when not to prefer: 'prefer ask_pipeworx for casual lookups.' Provides clear 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond, detailing fan-out behavior, response shapes, resolver contracts, parent-event extraction, news fallbacks, and safety checks (low-confidence, closed markets, wide spreads, cancellation rules). 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 comprehensive but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It front-loads the main purpose and progressively adds details. Every sentence provides necessary context; no wasted words.

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

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

No output schema exists, so the description compensates by detailing result fields (market, analysis, evidence), resolver contract (match confidence, alternatives), parent_event, news fields (fallbacks), and edge cases. It covers all likely agent queries for a complex research 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%. The description adds significant meaning: for 'market' it explains slug, URL, or question text with examples; 'depth' explains quick vs thorough with default; 'include_raw' explains purpose and impact on response size. 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 the tool researches a Polymarket bet by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and actions (resolve, classify, fan out, return evidence + comparison). It distinguishes from siblings like polymarket_arbitrage by focusing on comprehensive research.

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

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

The description explicitly recommends use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It provides detailed usage examples and classifier options. However, it could more explicitly state when not to use it or when to prefer sibling tools like polymarket_edges.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds context about data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. No contradictions.

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

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

Description is packed with useful information in a single paragraph. It includes examples and clear directives. Slightly long but still concise for the amount of detail. Could benefit from bullet points for readability but not detrimental.

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 2 params and no output schema, the description fully explains inputs, behavior, and output. Covers data sources, sorting, and return format. Adequate for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%. Description explains 'type' enum values (company/drug) and what each pulls. Clarifies 'values' format (tickers for company, names for drug) and bounds (2–5). Adds meaning beyond schema descriptions.

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

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

Description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs with specific verbs like 'compare', 'rank', 'head to head'. It distinguishes from sibling tool 'entity_profile' which is a single-entity lookup.

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 'ALWAYS PREFER over sequential single-pack lookups' and provides examples of when to use (comparing entities, ranking). Implies not to use for single entities. It replaces 8–15 sequential lookups, offering 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?

Adds rich behavioral context beyond annotations: describes return findings packet with verbatim evidence, gaps[], contradictions[], semantic excerpting, timing (15-60s), and stable citations. Annotations already indicate read-only, idempotent, open-world, 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 verbose but well-structured with clear sections (account, usage, what it does, alternatives, depth details, timing). Every sentence adds value, though could be slightly more compact.

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

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

For a complex tool with 1365 sources, 5211 tools, and multiple research depths, the description covers all essential aspects: parallelism, gaps, contradictions, semantic excerpting, timing, and return format. No output schema but return structure is described.

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

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

Schema covers both parameters with 100% description coverage. The description adds significant meaning: explains depth enum values in detail (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative hop) and clarifies question is natural language open-ended.

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 performs grounded multi-source research across Pipeworx's structured data, decomposes questions into facets, and routes to 5,211 tools in parallel. It distinguishes from siblings like ask_pipeworx (single lookup) and clarifies it's not open-web 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?

Explicitly states when to use: 'Best for broad/multi-part questions over structured data' and when not: for breaking news or current-events topics, prefer ask_pipeworx. Also mentions account requirements and provides alternative for unsigned users.

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, destructiveHint. The description adds that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This explains output format and readiness, adding value beyond annotations. No contradictions.

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

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

The description is two sentences: first states purpose with domain examples, second explains output and usage timing. Every sentence adds value, no fluff, and front-loaded with key information. It's well-structured and 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 complexity and the presence of schema coverage (100%), the description covers what it returns (names, descriptions, schemas, examples) and that results are callable. No output schema exists, but the description explains output adequately. It does not mention pagination or error handling, but it is sufficiently complete for typical use.

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

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

Schema coverage is 100% with explicit descriptions for each parameter. The description mentions aliases (q, task, search, description) and the limit parameter, but does not add new semantics beyond what the schema already provides. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides a comprehensive list of domains (SEC filings, FDA, etc.) and distinguishes this tool from siblings by explaining it returns tool schemas ready to call. The verb 'discover' is specific to browsing/searching, which sets it apart clearly.

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: '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 does not explicitly state when not to use, but the context implies it's for tool discovery only. No alternatives are named, but the tool is meta, so the guidance is clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields, notes a patent sunset (May 2025) that causes soft-fails. This provides useful transparency beyond annotations, though it omits rate limits or error details.

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 packed with information but well-structured: it opens with example queries in quotes, then explains the tool's purpose, lists data sources, and details return fields. It uses bold for emphasis. While long, every sentence serves a purpose; it could be slightly more concise but remains effective.

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

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

Given the tool's complexity (multiple sources, many return fields) and no output schema, the description covers most aspects: it lists all return fields (CIK, filings with URIs, fundamentals sorted by period, patents, news, LEI), specifies input constraints, and notes a known limitation. A minor gap is not clarifying which fields are always present vs. conditional on data availability.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by reinforcing that type only supports 'company' (with 'person/place coming soon'), specifying that value must be a ticker or zero-padded CIK, and clearly stating that names are not supported—urging use of resolve_entity. This guidance enhances agent 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 clearly states the tool returns a full cross-source profile of a US public company in one parallel call, using examples like 'brief me on Tesla' and listing the data sources. It differentiates from siblings by recommending use over chaining single-source lookups and directing name resolution to resolve_entity.

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

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

Explicitly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also specifies input requirements (ticker or CIK) and when not to use (names not supported, use resolve_entity first).

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context that 'clearance means FDA found substantial equivalence; it is not an FDA approval or endorsement,' which clarifies the meaning of results beyond the annotations. 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 concise sentences: the first covers the action and criteria, the second clarifies the regulatory meaning. No wasted words 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?

The description, combined with a complete schema (100% coverage) and an existing output schema, provides sufficient context for a search tool. It clarifies the meaning of clearance, which is critical for correct interpretation of results.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters. The description merely lists the searchable fields without adding new semantics or usage details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('Search') and the resource ('FDA 510(k) premarket notifications'), and lists specific search criteria (device, applicant, product code, K number). It distinguishes from sibling tools like fda_device_pma_search by focusing on 510(k) premarket notifications.

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

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

The description implicitly suggests usage for searching 510(k) clearance data, but lacks explicit guidance on when to use this tool versus alternatives such as fda_device_pma_search or fda_device_adverse_events. No 'when not to use' or exclusion conditions are provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds critical behavioral context: MAUDE reports are unverified and cannot establish causation, incidence, prevalence, or comparative safety. This goes beyond annotations to set expectations about data reliability.

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: the first states the purpose and search criteria, the second adds a critical caveat. Every word earns its place; there is no redundancy or unnecessary detail.

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

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

Given 7 optional parameters and an output schema, the description covers the search space and data limitations. It does not mention pagination, ordering, or empty result behavior, but these are less critical with the output schema present. The caution about data quality adds completeness.

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?

Input schema has 100% coverage with individual parameter descriptions. The description lists the same parameter categories (manufacturer, brand/device, product code, event type, PMA/510(k) number) but adds no new semantic detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool searches FDA MAUDE medical-device reports and lists specific search criteria (manufacturer, brand/device, product code, event type, PMA/510(k) number). It distinguishes from sibling FDA tools like fda_device_510k_search and fda_device_recalls by targeting adverse event reports.

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 caution that MAUDE reports are unverified signals and cannot establish causation, which guides appropriate use. However, it lacks explicit when-to-use versus alternatives (e.g., fda_device_event_counts) or conditions for use beyond the data quality warning.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: classification is for the category, not specific product clearance/approval, which is beyond the annotations.

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

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

Two sentences with no redundant words. Front-loaded with action and resource, followed by a critical caveat. 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?

Given the presence of an output schema, the description need not cover return values. It sufficiently explains the tool's purpose, scope, and search criteria, providing complete context for a read-only lookup 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?

With only 25% schema coverage, the description compensates by listing the three main search parameters (product code, device name, regulation number) and their roles. It does not detail the limit parameter, but the schema already describes it.

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

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

The description clearly states the verb 'Look up' and resource 'FDA device classification', with specific search criteria (product code, device name, regulation number). It distinguishes from siblings by clarifying that it describes the product-code category, not a specific product's clearance or approval.

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

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

The description specifies when to use (look up classification by given criteria) and implicitly differentiates from sibling tools for specific searches like 510k or PMA. However, it lacks explicit when-not-to-use or alternative recommendations.

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 important behavioral caveats: imperfect name matching and that MAUDE counts are signals, not safety rates, which provides context beyond annotations.

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

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

Two sentences: first states core purpose, second adds key caveats. No wasted words, front-loaded with 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 snapshot tool with output schema and clear annotations, the description covers purpose, datasets, and limitations. It could briefly mention how datasets are combined, but output schema likely provides structure.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by noting imperfect name matching for the 'company' parameter, implying fuzzy matching, which is not in the schema.

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

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

The description clearly states the verb 'Build' and resource 'FDA regulatory snapshot for one device company' across specific datasets (510(k), PMA, recalls, MAUDE). It distinguishes from sibling tools like fda_device_510k_search by focusing on a multi-dataset overview.

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 an aggregated snapshot of one company, but does not explicitly state when not to use it or mention alternatives like individual dataset 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by disclosing that registration/listing does not imply FDA approval, which is critical for interpreting results. This goes beyond what annotations provide, though it omits details like pagination or result limit behavior.

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

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

The description consists of two concise sentences: the first states the action and parameters, the second provides a crucial disclaimer. Every sentence earns its place with zero redundancy or fluff.

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

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

Given the 5 parameters with 0% schema coverage, the description is minimally adequate but lacks details like pagination, parameter interaction, or response structure (though output schema exists). The approval disclaimer is valuable, but overall completeness is moderate.

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 0%, so the description must carry the burden. It explicitly lists 4 of 5 parameters (firm, registration_number, product_code, listing_number), which is helpful, but omits 'limit'. No details are provided on how parameters interact (e.g., combinability, partial matching), leaving gaps.

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 specifies the resource 'FDA device registration/listing data', listing specific search parameters (firm, registration number, product code, listing number). This differentiates it from sibling tools that search other FDA data (e.g., 510k, adverse events). The disclaimer adds context without obscuring purpose.

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

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

The description implies usage when searching by the listed parameters, but provides no explicit guidance on when to prefer this tool over siblings like fda_device_510k_search or fda_device_classification. No exclusions or alternatives are mentioned, leaving the agent to infer from the resource name alone.

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 non-destructive behavior. The description adds valuable context about the statistical limitations of the counts, which goes beyond what annotations provide.

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

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

Two tight sentences: the first states the core functionality, the second delivers an essential caveat. No filler or redundancy.

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

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

Given the tool's simplicity (counting, three parameters), the description covers the purpose and key behavioral context. An output schema exists, so return value documentation is external. Sibling tools like fda_device_adverse_events complement this tool, and the description provides enough differentiation.

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 two of three parameters with descriptions (limit and query), and the count_field enum values are listed. The description merely paraphrases the enum options without adding new semantic detail. Schema coverage is 67%, so the description adds minimal additional meaning.

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

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

The description explicitly states the verb 'Aggregate' and the resource 'MAUDE reports', and lists the grouping options (event type, manufacturer, product code, receive date). This clearly distinguishes it from sibling tools like fda_device_adverse_events (which provides individual reports) and other FDA 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 includes a critical caveat that counts are artifacts and must not be compared without denominators, guiding the agent on appropriate use and limitations. However, it does not explicitly contrast with sibling tools or state when to use this tool over 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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds useful context: supplements may represent manufacturing/labeling changes, not new devices. This helps set expectations about the nature of results beyond what annotations provide.

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

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

Two efficient sentences: first states purpose and searchable fields, second adds a key nuance about supplements. No wasted words, front-loaded with essential information.

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

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

Given the presence of an output schema and 7 optional parameters, the description covers the core functionality and hints at result nuances. It is sufficiently complete for understanding how to use the tool, though could elaborate on default behavior (e.g., ordering, pagination) which is partially covered by the limit parameter description.

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

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

Schema coverage is 100% (all 7 parameters have descriptions). The description mentions some searchable fields (device, applicant, product_code, pma_number) but does not add semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states that the tool searches FDA PMA decisions and supplements by specific criteria (trade/generic name, applicant, product code, PMA number). It is specific about the resource and action, but does not explicitly differentiate from sibling tools like fda_device_510k_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?

No explicit guidance on when to use this tool versus alternatives. The description implies usage for PMA searches but does not provide when-not or alternative tool recommendations.

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, etc. Description adds valuable caveat: 'MAUDE counts are not event rates', and notes dataset counts have different meanings. Complements annotations well.

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

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

Two concise sentences: first defines purpose and contents, second adds essential warning. No superfluous text; front-loaded with key information.

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

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

Given output schema exists, description is largely complete for a read-only snapshot tool. Covers core function and a key caveat, though could mention how results are combined.

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

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

Schema has 0% description coverage. Description mentions 'one FDA product code' for product_code and 'bounded' for limit_per_dataset. Partially compensates but does not fully explain limit_per_dataset's role or format.

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

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

Description clearly states verb 'Build' and resource 'bounded cross-dataset snapshot for one FDA product code', listing included datasets. Distinguishes from sibling tools focused on single datasets.

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?

Implicitly indicates use for cross-dataset overview but lacks explicit when/when-not or alternatives. Context shows many siblings, but description does not guide selection.

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

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

Annotations already convey readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by clarifying that a recall record describes a correction/removal action and does not by itself establish patient harm, which is important contextual information beyond the annotation flags. However, it does not disclose other behaviors like rate limits, pagination, or sorting.

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

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

The description is two sentences long, front-loading the core action and parameters, and then adding a clarifying note. Every sentence earns its place 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?

Given the tool has 7 optional parameters and an output schema (unseen but present), the description adequately covers the tool's purpose and the nature of recall records. It lacks details on result ordering, pagination, or default sort, but the presence of an output schema reduces the need to explain return structure. Overall, it is sufficiently complete for an agent.

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

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

Schema description coverage is 100%, with each parameter already well-documented in the JSON schema (e.g., 'Recalling firm substring', 'Results (1-100, default 20)'). The description lists the parameters but adds no additional semantic meaning or usage context beyond what the schema provides.

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

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

The description clearly specifies the verb 'Search' and the resource 'FDA medical-device recall records', and lists the searchable fields. It distinguishes recall records from other FDA tools by noting the correction/removal action nature, but does not explicitly contrast with sibling tools like fda_device_adverse_events or fda_device_510k_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 states what the tool does and the search parameters, implying usage for recall lookups, but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it. There are no prerequisites or exclusions mentioned.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the tool is clearly a safe, read-only search. The description adds important behavioral context beyond annotations by warning that results do not imply current sales, clearance, or safety.

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

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

The description is two sentences long, front-loading the core purpose and adding a crucial disclaimer. Every sentence earns its place with 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?

An output schema is present, so return values need not be explained. The description covers the search intent and important disclaimers. It could mention that all parameters are optional, but given the presence of the schema and annotations, the description is reasonably 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?

With schema description coverage at only 20% (only 'query' has a description), the description should compensate. It mentions searchable fields ('brand, company, device identifier, or product code'), which aligns with the parameters 'query', 'company', 'primary_di', and 'product_code', but provides no details on the 'limit' parameter or input format. This adds moderate 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 'Search FDA GUDID/UDI records by brand, company, device identifier, or product code,' specifying the verb 'search' and the resource 'FDA GUDID/UDI records.' It also distinguishes the tool from sibling FDA tools (e.g., 510k, adverse events) by clarifying that the returned UDI records do not establish sales, clearance, or safety.

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 by stating what a UDI record represents and what it does not establish, helping agents avoid misinterpretation. However, it does not explicitly contrast this tool with siblings like fda_device_510k_search or give direct when-not instructions.

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 destructiveHint and idempotentHint. Description adds 'Delete' which aligns with destructiveHint but does not clarify behavior on missing key or idempotency. No contradiction as description omits detail 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, no waste. Purpose and usage are front-loaded. Every sentence earns its place.

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

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

For a simple delete operation with one parameter, no output schema, and comprehensive annotations, the description provides sufficient context including usage guidance and tool pairing.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to delete'. Description adds no extra semantic value beyond the schema, so baseline 3 applies.

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

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

Description clearly states 'Delete a previously stored memory by key' with specific verb and resource. It implicitly distinguishes from sibling tools 'remember' and 'recall' by naming them as counterparts.

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 ('context is stale, task is done, clear sensitive data') and mentions pairing with 'remember' and 'recall', providing clear guidance on context and alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable process details (fetches page, extracts title/links, emits standard format) and output nature. No contradictions.

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

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

The description is concise with about four sentences, front-loading the main action and listing use cases efficiently. No unnecessary information.

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

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

For a low-complexity tool (2 params, no output schema), the description fully covers purpose, usage, behavior, and output format, making it 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%, so baseline is 3. The description doesn't add new meaning beyond schema descriptions for url and max_links parameters.

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 generates a production-ready llms.txt file for any URL, using a specific verb and resource. It distinguishes itself from unrelated 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 use cases (client indexing, own project, competitor audit) that clarify when to use the tool. It doesn't explicitly state when not to, but the tool's specificity makes that clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds detail about the return fields but does not contradict annotations. No additional behavioral traits beyond what annotations convey.

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

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

Two sentences covering action, return fields, and usage guidance. Front-loaded with the core purpose, every sentence earns its place. No unnecessary text.

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, no output schema, and rich annotations, the description is complete. It specifies returned fields, usage context, and works well with sibling tools for subscribe/unsubscribe.

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

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

The schema already describes the single parameter 'include_inactive' with 100% coverage. The description does not add extra meaning or usage details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action (list subscriptions) and the resource (caller's active subscriptions). It specifies the returned fields. While it doesn't explicitly differentiate from siblings, the mention of reviewing before adding or canceling implies it's for inspection, not mutation.

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

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

The description explicitly states when to use the tool: to review monitored items before adding more or to find an ID to cancel. This provides clear context for its usage, though it doesn't explicitly state when not to use it.

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

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

Adds behavioral traits beyond annotations: rate limit (5/identifier/day), free usage (no quota), and mentions team reading digests and roadmap impact. No contradiction with annotations.

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

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

Four sentences, front-loaded with purpose, then usage, then constraints. No fluff. Every sentence adds value.

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

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

Given moderate complexity (3 params, nested object, no output schema), the description covers purpose, usage, constraints, and input guidance. No output schema needed for simple feedback. Complete.

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

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

Schema coverage is 100%, but description adds extra meaning for 'message' parameter (be specific, don't paste user prompt). Reinforces enum choices. Provides context beyond basic schema.

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

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

The description clearly states the tool's purpose: sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. It distinguishes from sibling tools (which are mostly query/search tools) by specifying feedback use cases.

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

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

Provides explicit when-to-use guidance for different feedback types (bug, feature, data_gap, praise). Also advises not to paste end-user prompts. Lacks explicit when-not-to-use but context is clear.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: caching (5min-1h), data source (CF analytics-engine), and privacy (no PII). 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 a single paragraph with clear organization: definition, use cases, additional context. Each sentence adds value, though it could be slightly more compact 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?

No output schema is provided, and the description only vaguely mentions 'top tools, top packs, and total call volume' without specifying the exact return format (e.g., whether it returns arrays with counts). This leaves some ambiguity for the agent.

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

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

Schema covers 100% of parameters with enum and description. The description adds default value (24h) and explains the trade-off between shorter and longer windows, providing meaning beyond schema definitions.

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 configurable time windows. It distinguishes itself from sibling tools like 'discover_tools' by focusing on aggregated usage trends rather than exploration.

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

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

The description explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tools, aligning with agent needs). It implicitly guides when to use but does not explicitly compare with alternatives like 'discover_tools' or state when not to use.

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

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

Annotations indicate read-only, open-world, idempotent. Description adds rich behavioral context: monotonicity violations, partition-sum checks, Jaccard similarity threshold, placeholder filtering, fill check against live CLOB depth. 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 thorough and well-structured, front-loading the core purpose and then detailing each mode. While slightly long, every sentence adds value and no trivial content is present.

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

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

Covers all aspects: no-args trending scan, event mode, topic mode, semantic anchor, partition filter, fill check, response structure, and reference to sibling tool for custom sizing. No gaps given the complexity and absence of output schema.

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

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

Both parameters are fully described in the schema (100% coverage). The description adds context: explanations of event slugs, topic seeds, and how each mode works, providing examples and use cases 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_edge_tracker by focusing on arbitrage detection.

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 explains when to use each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'pass topic for a themed cross-event scan'. Recommends event mode for specific markets and warns when not to trade based on fill check. Also references polymarket_fill_risk for custom sizing.

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

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

The description adds significant detail beyond annotations: model families, edge calculation, Kelly sizing, caching, and diagnostic info. Annotations already indicate read-only and idempotent, and the description is consistent.

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

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

The description is extremely long and dense with technical jargon, making it hard to parse quickly. While structured with sections, it lacks conciseness and is not front-loaded for an agent's efficient reading.

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

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

Given no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and what each opportunity contains. It covers filters and edge cases, making it complete for an agent to understand the tool's behavior.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds context (e.g., 'Tradeable-edge filters') and explains min_partition_leg_kelly nuance, but the schema already provides clear semantics for each parameter.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and positions it for daily discovery ('what should I bet on today'). This distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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 discovering edge opportunities and includes context like caching and segment diagnostics, but does not explicitly compare to sibling tools or state when not to use it.

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

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

The description goes far beyond annotations, explaining response structure (tracked, expired, snapshot_dates), limitations (60-day TTL, cache-miss gaps), and computational details (decay from daily closes, signed edge_pp_net). No annotation contradictions.

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

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

The description is relatively long but well-structured: purpose statement, args, response fields, and limits. Each sentence adds value. However, it could be slightly more concise by reducing redundancy in the response field explanations.

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

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

Despite no output schema, the description thoroughly explains all return fields and their semantics. It also covers limitations and operational details (cache-miss gaps, TTL). This gives the agent a complete understanding of what to expect.

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

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

Schema coverage is 100%, so both parameters are documented. The description adds context: default values (14 days, '1wk'), max for days (30), and explanation of 'window' as snapshot family. This adds 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 provides 'edge persistence and decay telemetry' and answers a specific question about edge duration and decay. The verb is implied (track/analyze), and the resource (polymarket edges over time) is clear. However, it does not explicitly differentiate from sibling tools like polymarket_edges, which likely focus on current edges without time-series.

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 direct usage context: 'Answers how long has this edge existed and is it shrinking?' This tells the agent when to use this tool. It does not explicitly exclude other tools or state when not to use it, but the context is sufficient. No explicit alternatives are mentioned.

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 show readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds rich behavioral detail: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict), and for baskets explains theoretical_sum vs realizable_sum, thin_legs, forced_directional_risk. No contradiction with annotations.

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

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

Description is front-loaded with purpose and constraints, then uses clear section headers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) for scannability. Every sentence adds specific value; no redundancy. 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?

No output schema, so description must explain return values. It does so thoroughly for both modes: lists all fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk). Also covers edge cases like partial fills and directional risk. Complete 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 description coverage is 100%. Description adds meaning beyond schema: explains side defaults and auto-detection for baskets, size_usd interpretation (max spend vs target proceeds for single-market, settlement notional for basket), and clamp range. This compensates fully despite no output 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 starts with a specific verb phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth', then clearly distinguishes two modes (single-market and basket). It explicitly links to sibling tools polymarket_arbitrage and polymarket_edges, stating when to use this tool instead, so purpose is unambiguous and differentiated.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the risk of not using it: theoretical overround not capturable and partial basket fills create unhedged directional positions. This provides clear context and exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds extensive behavioral detail: how spreads are computed, meaning of compatibility_warning, temporal alignment checks, and skipped cross-type/subtype counters. 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 verbose and contains some redundancy (e.g., explaining compatibility_warning cases twice). Well-structured with sections but could be more concise. Multiple sentences could be combined or removed without loss of meaning.

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

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

Despite no output schema, the description fully explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields like compatibility_warning, temporal_alignment, skipped counters). Covers edge cases and warnings, making it complete for a complex cross-venue 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%, providing baseline of 3. The description adds significant context: topic as a shortcut for 10 pre-mapped macros, explicit parameters override topic, and examples for topic usage. This goes beyond schema definitions.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings by specifying cross-venue and mentioning polymarket_arbitrage as a different tool. The verb 'cross-venue spread' is specific and resource-oriented.

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

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

Explicitly describes two modes (topic vs explicit parameters) and when to use each. Warns that most pre-mapped topics return compatibility_warning, setting expectations. Also explains when not to trust spreads (temporal misalignment, compatibility issues). Provides clear context on proper invocation.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context about scoping (anonymous IP, BYO key hash, or account ID) and pairing with remember/forget. 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 that efficiently convey the tool's dual behavior and usage context. No wasted words; front-loaded with the primary 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?

The description covers both operational modes (with and without key), scoping, and pairing with sibling tools. While there is no output schema, the description implies the return value (saved value or list of keys). It is complete for a simple retrieval tool with strong annotation support.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining the optional key behavior ('omit to list all keys') and giving concrete examples of what keys store (ticker, address, notes), which is beyond the schema's basic description.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys when no key is provided. It distinguishes itself from sibling tools 'remember' and 'forget' by explicitly mentioning them, aligning with the specific verb-resource pattern.

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 (look up context stored earlier) and when to omit the key (list all keys). It implies appropriate usage contexts but does not explicitly state when not to use it, though sibling tools cover other operations.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds valuable behavioral details: returns specific fields (source, citation_uri, raw payload), explains mark_read side effect, and notes polling suitability. No contradictions.

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

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

Concise and front-loaded with clear purpose, then brief details. Each sentence adds value: purpose, return fields, filters, mark_read, polling note, alternative endpoint. Slightly longer than minimal but 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 adequately explains return fields (source, citation_uri, raw payload) and behavior (filtering, mark_read, polling). With rich annotations, this is fully sufficient for correct usage.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds context for type (example 'sec_8k'), since (ISO timestamp), and mark_read behavior, but does not significantly enhance meaning beyond schema. Baseline 3 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 'Pull fired events from your subscription feed' with specific verb and resource, and distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on fired alerts from the subscription feed.

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

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

Provides explicit guidance on when to use: describes filtering by type and since, explains mark_read behavior for polling, and offers an alternative REST endpoint for scripts/dashboards. No exclusion of alternatives but clear context.

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

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

The description discloses behavioral traits beyond what annotations provide, including the fan-out to multiple data sources (SEC, GDELT→GNews fallback, USPTO), the soft-failure mechanism for USPTO, and the return structure (changes by source, count, citation URIs). No contradiction with annotations.

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

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

The description is well-structured, front-loaded with example queries, and every sentence adds value. It covers purpose, usage, internal behavior, parameter details, and alternatives without redundancy.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description is fully complete. It explains what the tool does, how it works, parameter format, limitations (USPTO sunset), and alternatives. 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?

Although schema description coverage is 100%, the description adds significant value by providing concrete examples for `since` (e.g., '7d', '30d', '3m', '1y') and suggesting typical monitoring values. It also clarifies that `type` is currently limited to 'company'.

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

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

The description explicitly states that the tool provides a change feed for a company over a time window, with clear example queries. It distinguishes itself from the sibling tool `entity_profile` by noting that `entity_profile` should be used for static profiles, regardless of time window.

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 with example queries and also specifies when not to use it (i.e., use `entity_profile` for static profiles). It includes parameter usage recommendations, such as default `since` values.

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

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

Discloses key-value pair storage scoped by identifier and memory duration (24h for anonymous). Annotations confirm write, idempotent, non-destructive. Could add whether overwriting is allowed, but overall adequate.

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 focused sentences with no extraneous content. Information is front-loaded and efficiently structured.

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

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

Covers persistence, use cases, and pairing with siblings. No output schema, but description explains what is stored. Could mention size limits but not essential.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds example key names but no extra semantic detail beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies the verb 'save' and the resource 'data', and distinguishes it from sibling tools like recall and forget.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward'. It also instructs to pair with recall and forget, and explains persistence differences between authenticated and anonymous sessions.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint false) already indicate safe, non-destructive behavior. Description adds value by noting internal cascading through multiple endpoints, replacing 2-3 manual lookups, which provides useful behavioral context beyond annotations.

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

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

Well-structured with leading examples, primary use case, then type details. Slightly verbose but each sentence adds value; no redundancy. Could be tightened but remains effective.

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

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

With no output schema, description fully explains return values: for company (ticker, CIK, name, citation URI) and for drug (RxCUI, ingredient, brand, citation URI). Also mentions auto-disambiguation, making it complete for a tool of moderate 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?

Input schema covers 100% of parameters. Description enriches by specifying return types per 'type' value and giving concrete examples for 'value' (e.g., ticker, CIK, brand/generic names). This adds clarity over 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?

Description provides specific verb (resolve) and resource (entity name to identifier). It includes example queries and distinguishes from siblings by clarifying it's the go-to for name-to-ID lookup, which is unique among sibling tools like compare_entities or entity_profile.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID.' Lists supported types with return details. Lacks explicit 'when not to use' or alternatives, but context strongly implies usage boundary.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds operational details: it probes with ai_visibility_check, ranks, and returns a ranked list with score/confidence/signal density. No contradictions; it enhances understanding beyond annotations.

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

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

Two sentences, each earning its place. The first sentence states the core action, the second provides context and output format. No fluff, well-structured.

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

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

Given the tool's complexity (4 params, no output schema), the description adequately covers purpose, internal mechanism, and output structure. It could mention entity count range (2-8) but that is in the schema. Still complete enough for typical use.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description does not add significant new meaning beyond what is in the schema descriptions, but it hints at the internal use of models. Baseline 3 is appropriate.

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

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

The description clearly states it compares AI visibility across multiple entities, using 'probes each entity with ai_visibility_check' and 'ranks by score'. It distinguishes itself from single-entity tools like ai_visibility_check 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?

The description explicitly says it is useful for competitive AI-marketing audits and gives a concrete example. While it doesn't list explicit alternatives, the context of comparing multiple entities implies when to use this over single-entity tools 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 already provide safety hints (readOnly, idempotent, non-destructive). Description adds critical behavioral context: fans out across two services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed list is included. 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 dense paragraph packs a lot of information efficiently. Could benefit from slight structuring (e.g., bullet points for return fields), but every sentence earns its place with 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?

No output schema, so description fully covers return values: summary block fields, per-advisory detail, links, alternative versions. Also explains timeout behavior and partial failure handling. Extremely comprehensive for a composite tool.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value by clarifying scoped packages are accepted for 'package' and providing an example version format ('18.3.1') for 'version'. Reinforces defaults behavior.

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 combo ('scan dependency') and immediately explains it's a composite check for npm packages combining deps.dev and bundlephobia data. Clearly distinct from siblings like 'deep_research' or 'validate_claim'.

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

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

Explicitly states use cases: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also specifies scope (NPM ecosystem only) and that other ecosystems should use deps.dev:version directly. Lacks explicit when-not-to-use, but context is clear given sibling list.

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 idempotent, read-only, open-world, non-destructive. Description adds critical behaviors: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flagging, and character offsets for verification. 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 with good front-loading of purpose and use cases. Slightly verbose but no irrelevant information. Could be split for readability but remains clear 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?

Coverage is exemplary: purpose, usage, technical details (model, windowing, truncation), and workflow pairing. No output schema exists, so description fully compensates by explaining return values (passages, offsets, scores). Meets all completeness criteria for this complexity level.

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

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

Schema coverage is 100%. Description adds value beyond schema: explains text max size with truncation behavior, provides query examples, and shows limit default and range. Enriches all parameters with practical context.

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

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

Clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article). Distinguishes from sibling ask_pipeworx_grounded by explaining the workflow: fetch with gateway, then ground over passages.

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 when the record is too big to cram into the prompt', and pairs with ask_pipeworx_grounded. Provides clear when-to-use and alternative tool reference.

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

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

Annotations indicate idempotency and non-destructive creation. Description adds details: account requirement, type-specific parameters, delivery constraints (SMS cap, webhook signing secret), and that subscriptions persist. 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?

Well-structured with key info upfront in first sentence, followed by organized details for types and delivery. While lengthy, it efficiently packs necessary complexity without redundancy.

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

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

Covers all relevant aspects: purpose, required authentication, type selection with examples, delivery options with limitations, return value, and side effects. No output schema needed as description sufficiently explains 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 enriches each parameter with concrete examples, type-specific filters, and delivery channel constraints that go well beyond the schema's brief descriptions.

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

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

Clearly states the verb (Create), resource (subscription to event stream), and outcome (returns id). Distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation and monitoring.

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?

Specifies when to use (proactive monitoring), required account type, supported types, and delivery channels with constraints. Implicitly contrasts with pulling alerts via recent_alerts or API endpoint, but could explicitly compare to alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant context: returns category-bucketed example questions with exact tool and argument shape. 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 appropriately sized for an onboarding tool, front-loading the purpose and examples. Every sentence adds value, though it could be slightly more concise. Structure is clear with examples and parameter guidance.

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

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

Despite no output schema, the description fully explains the return value: category-bucketed example questions with tool and argument shapes. It covers both no-argument and topic-focused calls. For an onboarding tool with many siblings, this is complete.

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

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

Schema coverage is 100% with one optional 'topic' parameter and description. The description adds meaning beyond the schema by listing specific topic values (finance, pharma, etc.) and stating that omitting it gives a cross-category spread, which helps the agent understand the parameter's effect.

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 an onboarding entry point for new users, listing example questions and what it returns. It distinguishes itself from siblings like ask_pipeworx and discover_tools by being the first thing to call when you don't know what Pipeworx can do.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains how to learn about meta-tools. Provides directive on when to pass 'topic'. However, it does not explicitly state when not to use it or offer alternatives beyond the listed 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?

Beyond annotations (destructiveHint=false, idempotentHint=true), the description discloses that the row is deactivated not deleted and that historical events remain 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, first sentence states action, second sentence provides important behavioral detail. No wasted words.

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

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

Given no output schema, the description covers what happens (deactivation), ownership, and linkage to historical data. Sufficient for agent to understand outcome.

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

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

Schema coverage is 100% with description for 'id' already provided in schema. The description adds no extra meaning beyond schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and resource 'a subscription by id'. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying cancellation via id.

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

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

It explicitly states ownership enforcement, guiding the agent to only cancel own subscriptions. It does not name alternatives but the context is clear enough. A slight gap is not mentioning when not to use, but the enforcement handles misuse.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context about the two processing pipelines, the return structure (verdict, actual value with citation, reasoning), and the fallback behavior for non-financial claims. This goes beyond the annotations without contradicting them.

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

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

The description is moderately long but front-loaded with usage examples and alternatives. Every sentence provides useful information, though it could be slightly more concise 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 complexity of the tool (two pipelines, return value structure) and the absence of an output schema, the description thoroughly explains the return format (verdict, actual value with citation, reasoning) and the routing logic for different claim types. It covers the key aspects needed for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds meaning by explaining that tolerance_pct overrides the implied tolerance from the claim wording and suggests specific values for hallucination detection. This adds 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 the tool is for natural-language claim verification, providing specific verb phrases like 'fact check' and 'verify the claim'. It distinguishes from siblings by describing the dual pipeline (SEC EDGAR for financial claims, grounded for others) and the efficiency gain.

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 whenever the agent needs to check whether something a user said is factually correct.' It provides examples of when to use, though it does not explicitly state when not to use, but the context from sibling tools and the detailed description sufficiently implies the appropriate use cases.

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