FDA Data MCP

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds the key context that results are aggregate annual summary counts from official reports, not detailed case-level data. This is useful but minimal; no additional behavioral traits like pagination behavior or data freshness are disclosed.

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

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

The description is two sentences with no fluff. The first sentence front-loads the exact action and resource, and the second adds essential scope clarification. Every word earns its place.

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

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

Given the 7 optional parameters, full schema coverage, and helpful annotations, the description provides enough context: the data source, granularity, and topic area. It lacks an explicit return-value structure, but the lack of an output schema is mitigated by the clear 'summary counts' phrasing. A brief note on return format would make it fully complete.

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

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

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The tool description does not add any extra parameter-level meaning beyond what the schema already provides, so the score stays at the baseline.

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

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

The description clearly states the tool searches for FDA's Biological Product Deviation Report annual summary counts, using specific verbs and resource names. It also distinguishes from per-event case detail, which uniquely identifies its scope among the many FDA search tools.

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

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

The description provides clear context on data granularity (summary-level vs. per-event) and explicitly notes what the tool does not do ('not per-event case detail'). However, it does not name an alternative tool for per-event searches, so it stops short of the explicit alternative guidance that would earn a 5.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true), the description adds substantive behavioral details: the data source (Compliance Dashboard data, not openFDA), hierarchical section-anchored CFR matching with concrete examples, and the join to parent inspection classification. It also discloses that results include source_url deep links. This far exceeds the minimum needed given annotations.

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

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

The description is dense but efficiently structured: purpose, filter options, matching behavior, return fields, then related tools. Every sentence adds distinct value—no filler or repetition of schema defaults. It is front-loaded with the core purpose and remains readable despite its length.

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

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

For a tool with 11 parameters, no output schema, and rich annotations, the description covers all essential aspects: what it searches, how filtering works, key edge cases (CFR matching), returned fields, and relationships to sibling tools. It lacks only minor details like default ordering, but those are not critical given the schema and the description's thoroughness.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant semantic value: it explains the tricky act_cfr_number prefix-matching behavior with examples, defines classification values (NAI/VAI/OAI), and clarifies fuzzy/partial matching for company_name and program_area. These details go beyond the schema descriptions, 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?

Description begins with a specific verb+resource: 'Search specific CFR violation citations from FDA inspections,' and immediately distinguishes from siblings by noting it uses Compliance Dashboard data not available in openFDA API. It also lists related tools with their distinct purposes, making the tool's role in the family clear.

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

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

The description provides clear usage context: 'Search specific CFR violation citations' and enumerates all filter dimensions, implying when this tool should be used. It also lists related tools for alternative needs (e.g., fda_inspections for classification by FEI, fda_search_warning_letters for official warning letters), which functions as alternative guidance. However, it does not explicitly state when NOT to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds domain context (CRL significance and definition) but does not disclose operational behaviors such as pagination behavior, return format, or edge cases, which would exceed annotation-provided information.

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

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

The description is three short sentences: the first establishes purpose and definition, the second lists filters, and the third adds regulatory significance and a related tool. It is front-loaded, succinct, and contains no redundant or wasted words.

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

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

For a straightforward search tool, the description covers what the tool does, what a CRL is, how to filter, and how it relates to another FDA tool. The absence of an output schema is compensated by the tool name and definition implying the return of letters, though specific response fields are not mentioned, preventing a perfect score.

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

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

The input schema already provides 100% coverage with descriptions for all parameters, including fuzzy match for company_name and array search for application_number. The description merely restates these filter options without adding new semantic meaning, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'Search' and resource 'FDA Complete Response Letters', and defines CRLs as formal refusal-to-approve decisions on drug and biologics applications. This clearly distinguishes it from sibling tools like fda_search_warning_letters and fda_search_opdp_untitled_letters by specifying a unique regulatory letter type.

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

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

The description provides clear context by explaining that CRLs are significant regulatory events indicating application deficiencies, and mentions fda_search_drugs as a related tool for approval status. However, it does not explicitly state when not to use this tool or enumerate all alternatives, so it stops short of a 5.

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

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

Annotations already declare read-only and idempotent hints, so safety is covered. The description adds valuable behavioral context: reverse-chronological ordering, combination of six event types, and inclusion of linked subsidiaries. This goes beyond what annotations provide, giving a concrete sense of the tool's output nature.

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?

A single dense sentence conveys the full purpose without fluff. Information is front-loaded with the main verb and object. Every clause is meaningful, so conciseness is excellent.

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

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

The tool is complex (aggregates six event types, includes subsidiaries), and there is no output schema. The description explains what the tool does but not the structure of the dated feed, event format, or how subsidiaries are resolved. It is minimally complete but misses some return-value details an agent might need.

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

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

Schema description coverage is 100%: all three parameters (company, limit, verbose) have adequate descriptions. The tool description does not add parameter-specific detail beyond the schema, so it stays at the baseline. No missing parameter information needs compensating.

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

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

The description starts with a specific verb ('Build') and resource ('compliance timeline'), and clearly distinguishes from siblings by noting it aggregates multiple event types (inspections, warning letters, import alerts, etc.) into one feed. This differentiates it from the individual search tools in the sibling list.

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 clearly states the tool's scope: one company and any linked subsidiaries. This implies it is the go-to for a consolidated compliance view, contrasting with individual search tools. It does not name explicit alternatives or exclusions, but the context is clear enough for an agent to decide when 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses a 5-credit cost, inclusion of known aliases, and specific exclusions. This adds meaningful behavioral context such as pricing and scope boundaries that are not present in the annotations.

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

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

The description is long but information-dense and well-structured, front-loading the core purpose then moving to exclusions and related tools. The related tool list is extensive but useful for agent navigation. No redundant sentences; each segment earns its place given the tool's breadth.

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 lack of an output schema, the description compensates by enumerating the exact included data categories and their sub-details (e.g., facilities with addresses and operations, enforcement actions as recalls). It also covers pricing, aliases, exclusions, and alternatives. It could be slightly more explicit about pagination behavior, but the parameter schema covers limit/offset mechanics.

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

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

Schema description coverage is 100%, with all parameters clearly documented. The description does not add significant parameter-level detail beyond mapping categories (e.g., drug applications, 510(k) clearances) to the limit/offset parameters, which is already implied by the parameter names and 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 defines the tool as a comprehensive company profile aggregator, listing specific content types (facilities, recalls, 510(k)s, PMAs, drug applications) and scope ('single company and its known aliases'). It distinguishes itself from siblings by explicitly stating exclusions and naming related 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 usage guidance: it states the tool is for single-company aggregate profiles, lists excluded categories (inspection history, warning letters, etc.), and gives alternative tools for family rollups and specific data types. It also names related tools like fda_suggest_subsidiaries, fda_inspections, and fda_compliance_actions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable context: the data source (Compliance Dashboard) and that these are the most serious regulatory outcomes typically following OAI inspections. This goes beyond the annotations without contradicting them, though it doesn't cover details like response format or pagination.

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

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

The description is three sentences long and front-loaded with the main purpose. It packs relevant context (data source, action types, filters, related tools) into a compact structure. The parentheticals make it slightly dense but 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 search tool with 6 well-documented parameters and no output schema, the description covers data source, filter options, example action types, and related tools. It lacks explicit mention of return structure (list of actions) but this is largely implied by the 'Search' verb and the tool's name, so it 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?

Schema description coverage is 100%, with every parameter described (limit, date range, fei_number, action_type, company_name). The description merely restates the filter options (company name, FEI number, action type, date range) without adding new meaning beyond the schema. Thus baseline 3 for high schema coverage is appropriate.

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

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

The description uses a specific verb+resource ('Search FDA compliance enforcement actions') and clearly distinguishes the tool from siblings by noting it covers Compliance Dashboard data (not in openFDA API) and specifying exact action types (Warning Letters, Seizures, Injunctions). This makes the purpose unmistakable.

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

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

The description gives clear context: data source (Compliance Dashboard, not openFDA), filtering capabilities, and related tools (fda_inspections, fda_citations) for underlying data. However, it does not explicitly tell the agent when not to use this tool versus other enforcement-related siblings like fda_search_enforcement or fda_ires_enforcement, so it's not a full 5.

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

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

Annotations already provide readOnlyHint and idempotentHint, and the description adds value by specifying the return content (reports with outcomes, reactions, product details) and the date format expectation. No contradictions with annotations; it supplements them with useful behavioral context.

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

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

A single, efficient sentence that leads with the action verb and resource, then lists filters and expected output. Every phrase carries meaning with no 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 tool has no output schema, the description appropriately mentions the report contents. It covers the main query dimensions and return details, but could optionally mention pagination defaults or that the date range applies to date_created. Still, it is sufficiently complete for a straightforward search tool with well-annotated schema and safety hints.

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

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

Schema coverage is 100% with each parameter well-described in the input schema. The description only summarizes the filter categories (product area, reaction, date range) without adding new semantics beyond what the schema already provides. This aligns with the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool searches consumer adverse events specifically for food and cosmetic products, with explicit filter dimensions (product area, reaction keyword, date range) and output content (outcomes, reactions, product details). This distinguishes it from sibling tools like fda_vet_events or generic enforcement searches.

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 the usage context: use when searching consumer adverse events for food/cosmetic products with optional filters. It does not explicitly mention alternatives or exclusions (e.g., not for veterinary events), but the context is clear enough for an agent to infer when to select this tool over others.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, covering safety and non-mutating behavior. The description adds behavioral context by specifying the required input format and the list of return fields, going beyond what annotations provide. No contradictions.

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

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

The description is three sentences, front-loaded with purpose and returns, then requirements, then related tools. 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?

For a single-parameter, read-only lookup tool with strong annotations and no output schema, the description adequately covers purpose, input requirements, return values, and alternatives. It is complete for the tool's complexity.

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

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

The input schema provides a basic description for product_code ('Device product code') with 100% coverage, but the tool description enriches this with the specific 3-letter code format and its sources (510(k), PMA, device product listings), aiding the agent in constructing valid input.

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

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

The description clearly states the tool's function with a specific verb ('Lookup'), the resource ('FDA device classification details'), and the method ('by product code'). It lists the specific data returned and distinguishes itself from related sibling tools (fda_product_code_lookup, fda_search_510k, fda_search_pma).

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 the prerequisite (product code from 510(k), PMA, or device product listings) and names three alternative tools with their distinct purposes, effectively telling the agent when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds that results include root cause, event type, and product codes, and mentions 'fuzzy match' for recalling firm, but this is also in the schema. No significant additional behavioral traits are disclosed, but the description 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?

The description is three sentences and front-loaded with the primary purpose. There is minor redundancy where 'Complements fda_search_enforcement' and the 'Related' list both mention fda_search_enforcement, but overall it is efficient and earns its place.

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

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

Given no output schema, the description compensates by specifying return details (root cause, event type, product codes). It also names related sibling tools. It does not mention pagination behavior, but offset/limit schema descriptions cover that. Overall, the context is quite complete for a read-only search tool.

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

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

Schema description coverage is 100%, so every parameter already has a description. The tool description lists the search criteria in prose but does not add meaning beyond the schema. A baseline score of 3 is appropriate since the schema handles parameter semantics.

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

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

The description uses the specific verb 'Search' with the resource 'FDA device recalls' and clearly states the search criteria (firm, product code, status, date range). It distinguishes from siblings by noting it complements fda_search_enforcement which covers all product types, and names related tools.

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

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

The description provides clear context by indicating this tool is for device-specific recalls, complementing fda_search_enforcement for all product types. It also lists related tools with brief explanations, giving the agent guidance on alternatives, though it could more explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is clear. The description adds contextual meaning (FDA official signal, medtech selling) but does not disclose additional behavioral traits like pagination behavior or rate limits. It neither contradicts annotations nor enriches them significantly, resulting in a baseline 3.

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

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

The description is two sentences, with the first sentence front-loading the core action and resource, and the second adding valuable context. Every sentence earns its place with no redundancy or filler.

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 9-parameter tool with no output schema, the description provides a solid overview of the tool's purpose and real-world relevance. It doesn't explain return format, but the search nature implies a list result, and the parameter schema covers the details. While more explicit sibling differentiation would help, the description is adequate for most use cases.

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

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

Schema description coverage is 100%, so each parameter's purpose is already documented. The description does not add parameter-specific meaning beyond the schema, only general context about categories and discontinuances. This meets the baseline of 3 but does not exceed it.

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

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

The description clearly states the tool searches FDA's current medical device shortage list and discontinuance list, using a specific verb ('Search') and resource. It distinguishes from sibling tools by specifying 'medical device' rather than drugs, and mentions 'shortage categories and permanent discontinuances'.

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

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

The description provides clear usage context by noting this is an official FDA supply-chain signal for medtech selling, covering shortages and discontinuances that may affect customer operations. However, it does not explicitly name alternatives or exclusions, such as pointing to fda_drug_shortages for drug-related 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?

The annotations already declare read-only and idempotent behavior. The description adds value by specifying the return data fields (brand name, company, device description, product codes, GMDN terms, sterilization info, premarket submissions), giving the agent an expectation of what the response will contain. No contradictions with the annotations.

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

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

The description is concise and well-structured: three sentences covering the action, the return data, and related tools. It is front-loaded with the core purpose, and every sentence earns its place without 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?

With the schema fully documenting parameters and the description covering purpose, return data, and related tools, the definition is largely complete for a read-only search tool. Minor gaps include the absence of guidance on behavior when no parameters are supplied and the lack of direct differentiation from the fda_device_udi_lookup sibling, but these do not significantly impair usability.

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 6 parameters, so the description does not need to add much. It lists the searchable fields (brand name, company, product code, DI number) but provides no additional per-parameter semantics beyond what the schema already documents.

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

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

The description clearly states the tool's function: searching the FDA UDI database by brand name, company, product code, or DI number. It also names related tools for differentiation, though it does not explicitly distinguish from the similarly named fda_device_udi_lookup sibling.

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

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

The description mentions related tools fda_device_class and fda_search_510k with their distinct purposes, implying that this tool is for general UDI searches. However, it lacks explicit guidance on when to prefer this tool over fda_device_udi_lookup or when to avoid using it, so usage context is implied rather than fully specified.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds that the operation 'Costs 1 credit', a useful behavioral detail not present in annotations. It also explains what the tool returns, giving extra transparency beyond the structured data.

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 concise sentences with the primary action front-loaded. It includes the database name, search keys, return values, and cost in fewer than 30 words. Every sentence earns its place 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?

For a tool with no output schema and six optional parameters, the description communicates the core purpose, searchable attributes, and key return content (UDI, descriptions, company info). It also notes the credit cost. It does not detail pagination or result caps, but schema descriptions already cover limit and offset, so completeness is adequate.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description mentions the main search fields (device ID, device name, company name, brand name) but does not add semantic detail beyond the schema, such as exact-match vs fuzzy-search behavior, which is already in the schema. It adds no new parameter insight.

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 the FDA's GUDID by device identifier, device name, company name, or brand name, and returns device details. It uses a specific verb ('Search') and names the resource (GUDID). It does not explicitly distinguish itself from the sibling tool 'fda_device_udi', but the description is unambiguous on its own.

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

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

The description provides clear context on when to use the tool: when looking up medical device information via DI/barcode, device name, company, or brand name. It does not explicitly mention alternatives or exclusions, but the search dimensions make the intended use obvious. No misleading guidance is present.

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

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

Annotations already establish read-only and idempotent behavior. The description adds that the tool returns 'complete label text for matching sections' and provides concrete section examples, which is useful context beyond the annotations. No contradiction found.

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

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

The description is four sentences, each serving a distinct purpose: scope, filters, return behavior, and related tools. It is front-loaded with the core action and contains no filler 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?

With no output schema, the description provides the essential return characteristic ('complete label text for matching sections') and enough filter/alternative context for a search tool. Pagination and limits are left to the schema, which is reasonable for a read-only operation.

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

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

The input schema already covers all 6 parameters with descriptions, so the baseline is 3. The tool description summarizes the filter types and adds one extra section example ('boxed_warning'), but does not substantially enrich understanding of parameter behavior 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 opens with 'Search FDA Structured Product Labeling (SPL) data — full drug package inserts', clearly identifying the action and resource. It distinguishes itself from siblings by naming fda_search_drugs and fda_search_ndc with their different scopes.

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

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

The description gives clear context by stating this tool returns full label sections and names related tools with their distinct purposes, implying when to choose an alternative. It does not explicitly state a 'when not to use' condition, but the alternative scopes effectively communicate that.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds domain context (supply chain strain, quality issues) but does not disclose behavioral details such as pagination behavior, status filter values, or result composition.

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

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

The description is compact at three sentences, with the purpose stated first, followed by relevant domain context and sibling differentiation. Every sentence contributes meaningful information 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?

For a read-only search tool with all-optional parameters, the description adequately covers purpose, query fields, and related tools. It does not describe return fields, but no output schema exists; still, the lack of status value examples or result details leaves minor gaps for a fully self-contained 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 description coverage is 100%, so the baseline is 3. The description repeats generic_name, company_name, and status but adds no new detail about parameter syntax or meaning. 'Availability' is mentioned as a search dimension without explanation, so no added 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 action ('Search') and the resource ('FDA drug shortages') and lists searchable fields. It distinguishes from siblings by naming fda_search_drugs and fda_search_ndc. However, it mentions 'availability' as a search dimension, which has no corresponding parameter in the schema, causing slight ambiguity.

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

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

The description provides a clear use case ('identifying companies with operational challenges') and names related tools with their different focuses (drug application data vs NDC-level details). It does not explicitly state when not to use this tool, but the contrast with siblings implies appropriate 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?

The annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds valuable behavioral context beyond the annotations: the compliance-first focus, the breadth of included data sections, freshness information, and the fact that it recommends next tools. 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 three sentences, each earning its place: the first states the core purpose, the second lists the return contents, and the third gives usage guidance. It is front-loaded with the most important information and contains no filler.

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 dossier tool with no output schema, the description adequately lists the major result categories (inspections, citations, warning letters, import refusals, recalls, etc.) and the intended use case. It could explicitly mention that evidence_limit applies per section, but that is already documented in the schema. The description is complete enough for an agent to understand what it will receive.

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

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

The input schema has 100% coverage for both parameters (fei and evidence_limit) with clear descriptions. The tool description adds no additional semantic meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool's function as a compliance-first facility dossier keyed by FEI number, and enumerates the specific contents (inspections, citations, warning letters, import history, recall context, etc.). It also distinguishes itself from the 'broader product-focused facility profile', making it easy to differentiate from sibling tools.

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

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

It explicitly says when to use the tool ('when you want the fastest FEI-level manufacturing risk view') and contrasts it with the alternative ('instead of the broader product-focused facility profile'). However, it does not name a specific sibling tool, so it falls short of fully explicit alternative naming.

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

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

With readOnlyHint and idempotentHint already present, the description adds behavioral context by explaining the pagination-focused use case and that the tool is device-specific. It also notes that fda_get_facility includes products, which helps the agent understand data overlap and avoid redundant calls. 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 front-loaded with the core purpose and return value specifics, and it is four sentences long. The final 'Requires: FEI number' is redundant with the schema, costing some conciseness, but overall the description is 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?

The tool is simple, the schema fully documents parameters, and the description lists the return fields and provides usage context pointing to related tools. The absence of an output schema is compensated by the explicit field list, making the description complete for its complexity.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description mentions pagination and the FEI requirement but adds no parameter-specific details beyond what the schema provides, meeting the baseline for full coverage.

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

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

The description uses the specific verb 'List' and identifies the resource as 'device products registered at a facility by FEI number'. It also names the returned fields and explicitly distinguishes this from fda_get_facility, which already includes products, making the tool's niche clear.

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

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

It states 'use this only when paginating through large product lists', providing an explicit condition for use. It also gives an alternative for drug products: 'use fda_search_ndc with company name instead', covering both device vs drug contexts.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe read-only nature is known. The description goes beyond by detailing the exact fields returned, the exclusions, and the relationships to other tools, providing a clear behavioral contract 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 long but highly structured: returns, requires, excludes, related tools. Every sentence carries meaningful information for a complex tool. It is more comprehensive than concise, but its length is justified by the tool's complexity.

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

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

Given the absence of an output schema, the description thoroughly covers return fields, prerequisites, exclusions, and sibling alternatives. It provides a complete picture of when and how to invoke the tool, making it self-sufficient for an agent.

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

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

All three parameters have descriptive entries in the schema (FEI pattern, numeric limits for products_offset/limit). The description mentions the FEI requirement and suggests sources, adding slight context, but does not significantly enhance the schema's parameter documentation. Baseline of 3 applies due to 100% schema coverage.

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

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

The description clearly states it provides a detailed facility profile by FEI number, enumerating the specific data returned. It distinguishes itself from sibling tools by listing exclusions and related tools for other use cases (e.g., fda_inspections for inspection details).

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 the required input (FEI number) and where to obtain it (fda_search_facilities or fda_company_full). Also specifies what is excluded and names alternative tools for those needs (inspections, citations, compliance actions, import refusals, facility products).

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

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

Annotations already declare readOnlyHint and idempotentHint, which are consistent with the 'Search' action. The description adds useful behavioral context: the data source (Compliance Dashboard, not openFDA API) and the meaning of results (detained at US border), going beyond annotation basics.

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

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

Three concise sentences: first identifies the tool and data source, second explains the domain meaning, third lists key filters and related tools. 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?

For a filtered search tool with well-described optional parameters and no output schema, the description provides sufficient context: what the data represents, why it matters, what filters are available, and related follow-up tools. The agent can confidently select and invoke this tool.

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

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

Schema descriptions cover 100% of parameters, so baseline is 3. The description adds value by highlighting the most relevant filter dimensions (company name, FEI, country code, date range) and gives concrete examples for country_code (CN, IN), which helps the agent pick parameters for the stated use case.

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 searches FDA import refusals and defines them as products detained at the US border. It differentiates from generic openFDA tools by noting this data comes from the Compliance Dashboard and is not in the openFDA API, but it does not explicitly contrast with the similarly named sibling fda_search_import_alerts.

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

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

Provides clear context for when to use: critical for evaluating international manufacturing sites and supply chain risk. It also names related tools (fda_get_facility, fda_inspections) for follow-up by FEI, though it does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds valuable context that the data is aggregate trend data by product area and citation frequency, which sets expectations for the type of results. However, it does not disclose return format or pagination behavior, which could have been useful given the lack of an output schema.

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

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

The description is three concise sentences that are front-loaded with the primary action ('Search...'). Each sentence contributes distinct value: the resource, the data nature, and the use case. There is no redundancy or filler.

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

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

Given there is no output schema, the description reasonably explains the data scope and purpose, including the aggregate nature and product areas. It does not detail the exact result structure, but for a simple search tool with clear annotations and schema, the description is sufficiently complete to set expectations.

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

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

Schema description coverage is 100% with all 7 parameters clearly described. The description does not add additional parameter-specific meaning beyond schema, but it does reinforce the product_area concept by mentioning Drugs, Devices, Foods. This aligns with the baseline score of 3 for high schema coverage.

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

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

The description clearly states the tool searches FDA's official annual inspection-observation summary spreadsheets, with a specific verb and resource. It further distinguishes the tool by noting it provides aggregate Form 483 trend data by product area and citation frequency, not a full company-level 483 corpus, which effectively separates it from sibling tools like fda_inspections.

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

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

The description gives explicit usage guidance: 'Use it to see which observation areas appear most often' provides a clear when-to-use, and 'not a full company-level 483 corpus' provides an explicit when-not-to-use. While it does not name an alternative tool, the stated exclusions are sufficient to guide tool selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description builds on that by adding source context (Compliance Dashboard vs openFDA), classification semantics (NAI/VAI/OAI severity), and the behavior that date filters apply to inspection_end_date. This adds useful behavioral nuance 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 compact and front-loaded with the main purpose. It wastes no words, packs in filter details, classification explanations, and related-tool pointers in three sentences. 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 read-only search tool with no output schema, the description covers the data source, filter types with special semantics, and related follow-up tools. It does not mention pagination or response format, but those are partly addressed by the limit parameter in the schema. The description is sufficiently complete for an agent to decide to invoke it.

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

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

The schema covers 100% of parameter descriptions, so the description's extra semantic details are valuable: company_name is a fuzzy match, classification_code values are expanded with their meanings and relative severity, and date filters are explicitly tied to inspection_end_date. This elevates the description above merely repeating 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 opens with a specific verb and resource: 'Search FDA inspection history from the Compliance Dashboard.' It clearly distinguishes this tool from siblings by noting it is not available in the openFDA API and by naming related tools (fda_citations, fda_compliance_actions) for different purposes.

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

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

The description gives clear context for when to use this tool: to search inspection history with various filters. It also provides alternatives via 'Related: fda_citations... fda_compliance_actions...' and explains that OAI inspections typically lead to warning letters, which helps the agent decide whether to use this tool or fda_compliance_actions. It does not explicitly state exclusions (e.g., 'use X instead when...'), so it is not a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds meaningful context by explaining the cross-referencing behavior and what the response includes (event classification, product codes, quantities), which 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 three sentences with the core purpose in the first sentence, filter details in the second, and return/related tools in the third. Every sentence earns its place, and the structure is front-loaded and scannable.

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

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

For a search tool with 7 parameters and no output schema, the description covers the main purpose, filters, return content, and related tools. It does not explicitly mention pagination, but the schema documents limit/offset. Overall, it provides enough context for an agent to invoke correctly, with minor gaps around usage constraints.

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

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

All 7 parameters have schema descriptions (100% coverage), so the baseline is 3. The description's filter list ('company name (fuzzy match), recall number, product type, date range') mostly restates the schema, though it does add product type examples. It does not provide additional semantic clarification beyond what the schema already offers.

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 begins with the specific action 'Search iRES enforcement recalls' and immediately distinguishes from siblings by noting cross-references to openFDA enforcement data and naming related tools. This gives a clear verb+resource+scope that is distinct from similar tools like fda_search_enforcement.

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

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

The description provides related tools as alternatives (fda_search_enforcement, fda_recall_facility_trace) and lists filter dimensions that suggest use cases. However, it lacks explicit 'use when' or 'not when' guidance, leaving the user to infer the best context from the 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 convey idempotency and non-destructiveness. The description adds behavioral context beyond this: it preserves alias collision safety and makes summaries family-aware. This provides useful insight into the tool's effect on downstream data. It does not contradict annotations and adds value without over-explaining.

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

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

The description is three sentences, each earning its place: purpose, usage scenario, and benefit. It is front-loaded with the action verb and immediately conveys the tool's role. No fluff or redundancy.

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

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

Given the tool's moderate complexity (2 params with nested array) and the absence of an output schema, the description covers the key aspects: what it does, when to use it, and its effect. It could mention what happens on successful linking or any prerequisites, but the example and context suffice for a 4.

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

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

Schema description coverage is 100%, so the baseline is 3. The description enhances parameter understanding by giving real-world examples (Actavis/Cephalon as subsidiaries, Teva as parent) and explaining the purpose of linking (family-level rollups, alias collision safety). This goes beyond the schema's generic field descriptions, justifying a 4.

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

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

The description clearly states the tool's function: 'Explicitly link existing company records under a parent company for family-level rollups.' It names specific example subsidiaries (Actavis, Cephalon) and a parent (Teva), making the purpose concrete. This distinguishes it from sibling tools like fda_suggest_subsidiaries or fda_save_aliases by focusing on linking existing records rather than suggesting or aliasing.

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

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

The description gives explicit usage context: 'Use this when names like Actavis or Cephalon already belong to their own company_id and should roll up under a parent like Teva.' This tells the agent when the tool is appropriate. However, it lacks explicit when-not-to-use guidance or direct mention of alternatives, so it falls short of a perfect 5.

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

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

Annotations declare readOnlyHint and idempotentHint, and the description adds meaningful context beyond annotations: cost per call, alias handling, inclusion of facilities with addresses/operations, enforcement recalls, and explicit exclusions. This gives a clear behavioral contract without contradicting annotations.

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

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

Three sentences: purpose, exclusions, and related tools. Every sentence adds value, no fluff, and the most important information (what it does, cost, exclusions) is front-loaded.

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

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

Despite no output schema, the description covers return content (facilities with addresses/operations, enforcement recalls), cost, alias behavior, and exclusions. It also points to related tools for broader data, making the tool's place in the ecosystem clear and sufficient for use.

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

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

Schema coverage is 100% with descriptions for all five parameters, so the baseline is 3. The description does not add any parameter-level detail beyond what the schema already provides; it mentions company lookup but does not elaborate on limits or offsets.

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

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

The description clearly states the tool performs a 'quick company lookup' for facilities and enforcement actions, with specific attributes (addresses, operations, recalls). It distinguishes from siblings by listing exclusions (510(k), PMA, drugs, inspections) and naming related 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?

Explicitly says 'Costs 1 credit' and 'Excludes' important categories, guiding when to use this tool versus alternatives. It names related tools with their differing scope and cost, such as fda_company_full for 5 credits and fda_suggest_subsidiaries for discovering related entities.

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

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

Annotations already declare readOnly and idempotent hints, establishing a safe operation. The description adds value by disclosing the data sources aggregated and the summary-centric behavior, which goes beyond annotations. No contradictions detected.

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, front-loaded with the core purpose and immediately followed by usage guidance. No wasted words; every phrase contributes to 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?

For a complex aggregation tool with no output schema, the description adequately covers the data sources and the intended use case. It does not describe the return format, but the listed data sources give a concrete sense of the summary content. Slight gaps remain about behavior on unknown companies or result shape, but overall it is sufficient.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description adds no additional parameter context, matching the baseline expectation of 3 when the schema carries the load.

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

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

The description clearly states a specific action ('Build a manufacturing and compliance summary') and resource ('one company'), listing the data sources involved and differentiating from granular tools by emphasizing the 'company-level picture first'. It effectively positions itself as a high-level aggregation tool.

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

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

The description offers explicit usage context: 'Use this when you want the company-level picture first' and advises following 'linked granular tools' for deeper inspection. It implies when not to use it (for detailed dives) and points to alternatives, though without naming specific sibling tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe read-only nature is established. The description adds behavioral context beyond the annotations by stating that it returns classification info plus paginated lists of all clearances and approvals, which is not captured by the annotations or schema alone.

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

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

The description is compact and front-loaded with the core action and return value. However, the final sentence 'Requires: product code' is redundant with the input schema and does not add value, preventing a perfect score.

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

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

For a read-only lookup tool with no output schema and a fully documented input schema, the description adequately explains what is returned (classification info plus paginated clearances/approvals) and the intended use case. It could mention empty-result behavior or how to navigate pagination more explicitly, but it is largely complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters including product_code, approvals_limit, approvals_offset, clearances_limit, and clearances_offset. The description only adds 'Requires: product code,' which is redundant with the schema's required field, providing no additional semantic guidance.

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

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

The description clearly states the tool's function with a specific verb ('Cross-reference') and resource ('device product code across classification details, 510(k) clearances, and PMA approvals'). It also distinguishes itself from sibling tools like fda_search_510k and fda_search_pma by focusing on cross-referencing across all three data types in one call.

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 the tool: 'Use to understand the regulatory landscape for a specific device type.' It does not mention when not to use it or list alternative sibling tools, but the intended use case is clear enough for an agent to select it appropriately.

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

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

Even though annotations already declare readOnlyHint and idempotentHint, the description adds meaningful behavioral detail: the tool resolves the best-matching recall automatically on the firm path, uses fuzzy matching, and returns explicit confidence levels and match methodology. This goes beyond the structured annotations and helps the agent predict behavior accurately.

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

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

The description is concise and front-loaded with the core purpose. It uses four sentences to convey purpose, matching methods, output contents, and usage alternatives without unnecessary detail. Every clause 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 tool with 3 optional parameters and no output schema, the description fully covers what the agent needs: input options, resolution behavior, return contents, and related tools for further enrichment. It is self-sufficient for selection and invocation.

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

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

Schema coverage is 100% and each parameter has a description, but the description adds value by explaining the relationship between parameters: recall_number is preferred, firm is a convenience path that auto-resolves, and product is optional to narrow firm-based resolution. This contextual parameter guidance exceeds the baseline schema-only semantics.

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

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

The description opens with a specific verb and resource: 'Trace a recall to its candidate manufacturing facility with explicit confidence levels.' It clearly states the matching methods (firm name, NDC lookup, facility registration data) and outputs (recall details, facility candidates with FEI numbers, confidence scores, methodology), distinguishing it from sibling tools like fda_search_enforcement and fda_get_facility.

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

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

Provides explicit usage instructions: 'Provide either recall_number (from fda_search_enforcement or fda_ires_enforcement) OR firm (+ optional product) to resolve the best-matching recall automatically.' It also names related tools for next steps ('Related: fda_get_facility, fda_inspections, fda_compliance_actions'), making when-to-use and alternatives 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=true, openWorldHint=false, and idempotentHint=true. The description adds value by specifying the return contents (canonical slug, match confidence, alias names) and the limitation that it does not discover new aliases. This goes beyond basic annotations, though it does not mention error behavior or performance.

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

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

The description is three sentences long, front-loaded with the primary purpose, then return details, then related-tool guidance. Every sentence serves a distinct purpose 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?

With a single simple parameter, strong annotations, and no output schema, the description includes return fields and related tools, making it complete for a lookup tool. There are no unexplained behaviors or missing crucial context.

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

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

Schema coverage is 100% with the 'company' parameter described as 'Company name to resolve'. The description restates this concept ('Resolve a company name') but adds no new semantics such as formatting, case sensitivity, or examples. The baseline is 3 due to high schema coverage.

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

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

The description uses a specific verb ('resolve') and resource ('company name to canonical company_id'), and clearly states it lists known aliases. It distinguishes from siblings by explicitly saying it does not discover new aliases and references related tools like fda_suggest_subsidiaries and fda_company_full.

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 names alternative tools and when to use them: fda_suggest_subsidiaries for discovering potential subsidiaries not yet aliased, and fda_company_full for a full profile using the resolved name. The 'does not discover new aliases' exclusion clarifies when not to use this tool.

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

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

Annotations already indicate idempotent, non-destructive write behavior, and the description adds crucial behavioral context: it updates confidence, tracks collisions, and implies collision handling (redirecting to fda_link_subsidiaries). This goes beyond the structured annotations, disclosing expected outcomes and edge cases 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 and front-loaded, with four sentences that are all informative: action, use case, collision handling, and workflow. 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 only two parameters and no output schema, the description is remarkably complete. It explains the exact scenario, provides a workflow with sibling tools, and handles collision edge cases. The agent has enough context to invoke correctly without additional clarification.

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

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

The input schema already documents both parameters (parent_company, aliases) with property descriptions, so coverage is 100%. The description adds extra semantic value by qualifying aliases as 'normalized' and 'confirmed same-entity', helping the agent understand what data to pass, 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 identifies the action ('Save normalized alias names for a parent company'), the target resource (company aliases), and differentiates from related tools by explicitly naming fda_link_subsidiaries and fda_suggest_subsidiaries. This goes beyond a vague 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?

It states exactly when to use this tool ('true name variants of the same company record'), when to avoid it (collision indicating another company_id, use fda_link_subsidiaries), and provides a typical workflow (call fda_suggest_subsidiaries first, review, then call this). This is explicit, actionable guidance with alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds useful behavioral context beyond these annotations, such as the fuzzy-match behavior for company names and the specific return fields (K-number, applicant, device name, decision date, product code). While it doesn't mention pagination or rate limits, the annotations reduce the burden, so a 4 is appropriate.

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

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

The description is concise and front-loaded, with a clear structure: purpose in the first sentence, filters/returns in the second, and related tools in the third. Every sentence earns its place, and there is no redundancy or irrelevant 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?

For a search tool with 8 parameters and no output schema, the description adequately covers the main filters and return values, and it points to related tools for further context. The schema fills in parameter specifics, making the description sufficiently complete without over-explaining.

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

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

With 100% schema description coverage, the baseline is 3. The description adds extra semantic meaning by explaining decision code examples (e.g., SESE=substantially equivalent) and expanding clearance type examples to include 'Abbreviated', which enriches the parameter context beyond the schema. This justifies a score above baseline.

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

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

The description clearly states the action ('Search') and the resource ('FDA 510(k) clearances') with an explicit scope ('across all companies'). It enumerates specific filters and return fields, and distinguishes itself from sibling tools by naming related tools and their purposes, making its unique role unambiguous.

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

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

The description provides explicit guidance on tool selection by listing related tools with their purposes: fda_device_class for product code details, fda_product_code_lookup for cross-referencing, and fda_search_pma for higher-risk devices. This effectively communicates when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds value by specifying the return fields (license number, company name, full address, establishment type, divisions, subsidiaries) and the covered facility types. This goes beyond what annotations alone provide, though it doesn't mention rate limits or pagination 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 is three sentences: the first states the purpose and filters, the second lists the return fields, and the third covers scope and a related tool. Every sentence earns its place with no redundancy or filler.

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

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

With no output schema, the description compensates by enumerating the return fields, which is crucial for an agent to know what to expect. It also defines the domain (vaccine manufacturers, diagnostic kit producers) and links to a related tool. The main gap is not specifying geographic coverage or data provenance, but overall it is sufficiently complete for a search tool with optional filters.

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, with each parameter clearly documented (e.g., 'Company name (fuzzy search)', 'State code (e.g., CA, NY)'). The description merely references 'company, state, or establishment type' without adding any new syntax or format details, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Search APHIS veterinary biologics establishments' with specific filters (company, state, establishment type). It distinguishes from siblings by focusing on this niche domain and lists relevant facility categories (vaccine manufacturers, diagnostic kit producers), leaving no ambiguity.

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

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

The description provides clear context: it searches establishments, not adverse events, and explicitly names a related tool (fda_vet_events) for the latter. However, it does not explicitly exclude other search tools like fda_search_facilities or provide when/when-not guidance, so it falls short of a full 5.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context: searching multiple datasets simultaneously and returning matches with product codes and company names. 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 three sentences with no filler. The first sentence front-loads the core action and scope, the second specifies datasets, and the third gives usage context and return contents. Every sentence contributes value.

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

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

Given no output schema, the description adequately explains return values (matches from each dataset with product codes and company names) and covers the search scope. It could mention pagination implications for large result sets, but the schema already documents limit/offset, so this is not a critical gap.

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

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

Schema coverage is 100%, giving baseline 3. However, the description expands on the product_name parameter by listing accepted name types (device name, trade name, generic name, brand name), which adds meaning beyond the schema's 'Product or brand name (fuzzy search)'. This additional detail justifies a 4.

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

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

The description clearly states a specific verb ('Search') and resource ('FDA device and drug datasets') and enumerates the exact datasets covered (device classifications, 510(k) clearances, PMA approvals, NDC records). This distinguishes it from sibling tools like fda_search_510k and fda_search_ndc, which target 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?

The description explicitly says 'Use when you know a product name but not which dataset it's in,' providing a clear when-to-use condition. However, it does not name alternative tools or state when not to use it, so it falls short of the full 'when/when-not/alternatives' ideal.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds that lists are 'current' and that records are 'high-severity compliance signals', which is useful domain context but does not disclose operational behaviors like pagination limits, rate limits, or specific return format beyond what annotations imply.

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

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

The description is extremely concise: two sentences, the first stating the exact action and scope, the second providing significance. Every word earns its place, with 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 the full schema coverage, rich annotations (readOnly, idempotent), and optional parameters, the description plus schema provide sufficient context for a search tool. However, since no output schema exists, the description could have briefly mentioned what fields are returned, but it's not a major gap for a simple search operation.

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

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

Schema description coverage is 100% with all 7 parameters described. The description itself adds no parameter-level detail beyond the schema, so the baseline of 3 is appropriate. It does not clarify fuzzy matching behavior or date-range semantics beyond what parameter descriptions already provide.

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

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

The description uses a specific verb 'Search' and a clear resource 'FDA debarment lists' with three explicit categories (drug applications, drug imports, food imports). This distinguishes it from sibling tools like fda_search_enforcement or fda_search_warning_letters, which cover different FDA enforcement areas.

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

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

The description provides clear context that debarments are 'rare but very high-severity compliance signals', implying use for high-stakes compliance checks. However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks explicit exclusions despite clear usage context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context by noting fuzzy matching for company names and specifying that the tool returns application details including products and submissions. No contradictions or missing critical caveats.

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 core function and filters, the second lists return contents and related tools. It is well-structured, front-loaded, and contains 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?

Even without an output schema, the description clearly states what will be returned (products, brand names, dosage forms, active ingredients, submissions, approval dates, status). It also names several sibling tools to help an agent route to a more specific tool when needed.

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

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

Schema coverage is 100% and every parameter has a description, so the schema already carries the main load. The description restates the filterable fields and adds the 'fuzzy match' detail for company, but it doesn't add significant meaning beyond the schema's parameter descriptions.

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

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

The description uses a specific verb ('Search') with a clear resource ('Drugs@FDA applications') and scope ('across all companies'). It also distinguishes the tool from related siblings by mentioning the result fields and listing alternative 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 a 'Related' list with explicit alternative tools for NDC-level data, labels, clinical letters, and shortages, which helps an agent choose between tools. However, it doesn't state explicit when-to-use/when-not-to-use conditions beyond those alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral details: fuzzy matching for company, classification severity ('Class I=most serious'), and return content ('product description, reason, distribution pattern'). It 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?

The description is compact and front-loaded: first sentence defines scope, second lists filters, third describes return details, fourth provides sibling alternatives. 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 7 optional parameters, no output schema, and a broad sibling list, the description covers purpose, filters, return content, and relationships to related tools. It provides sufficient context for correct selection and invocation without external documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description enhances parameter understanding by explaining fuzzy match behavior for 'company', clarifying classification levels ('Class I=most serious/Class II/Class III'), and grouping date range/status as filter categories, adding 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 verb ('Search'), resource ('FDA enforcement actions/recalls'), and scope ('for drugs, devices, and food across all companies'). It distinguishes itself from siblings by naming alternative tools like fda_recall_facility_trace and fda_device_recalls with their specific purposes.

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 lists filter criteria (company, classification, date range, status) and includes a 'Related:' section that tells when to use alternative tools (e.g., trace to facility, iRES data, device-specific recalls). This provides clear when-to-use guidance and exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral context by stating it searches two specific databases, returns FEI number/name/address/source, and explicitly excludes related data categories. No contradiction with annotations; the added scope 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?

The description is four sentences, each adding a distinct piece of information: purpose, operations parameter guidance, country filter usage, and exclusions/related tools. No redundant phrasing or filler; 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?

Despite having 7 parameters and no output schema, the description covers search dimensions, return fields, exclusions, and related tools. The schema fully documents each parameter, and annotations confirm read-only safe operation, leaving no significant context gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by giving concrete examples for operations ('Contract Manufacture', 'API', 'Repack') and country (ISO codes US, DE, IN, CN, IE), and explains the strategic purpose of the country filter for mapping global manufacturing footprint.

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

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

The description opens with 'Search FDA-registered facilities by name, city, state, or country,' which clearly states the verb, resource, and scope. It further distinguishes itself by specifying that it searches drug (DECRS) and device registration databases and mentioning related tools like fda_get_facility, fda_inspections, and fda_citations.

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

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

It explicitly instructs when to use the operations parameter ('filter by manufacturing type') and country filter ('map a company's global manufacturing footprint'). It also names alternatives and lists exclusions ('products at facility, inspection history, enforcement actions'), giving clear decision support.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, which communicate the safety profile. The description adds context about linked subsidiaries, which is useful, but does not disclose any additional behavioral traits such as pagination behavior, result format, or rate limits. Given the strong annotation coverage, a score of 3 is appropriate.

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 and front-loaded: the first sentence states the core purpose, the second provides usage context and lists filters. Every sentence adds value, and there is no redundancy or filler.

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 search tool with no output schema, the description covers the essential aspects: what it searches, when to use it, and the available filters. Pagination details are already in the schema via limit/offset. The lack of return-value documentation is a minor gap, but not critical for a read-only search operation with full schema coverage.

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 7 parameters, so the schema itself carries the semantic load. The description only lists optional filters (city, state, country, operations) without adding meaning beyond what the schema already provides. The baseline is 3 for high schema coverage.

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

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

The description clearly states a specific verb ('Search') and resource ('FDA-registered facilities across a parent company and any explicitly linked subsidiaries'), and distinguishes this from the sibling tool fda_search_facilities by highlighting the parent/subsidiary scope. Examples of child entities (Actavis, Watson, Cephalon) reinforce purpose clarity.

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

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

The description explicitly states when to use the tool: 'Use this when you know the parent company but the FDA records may sit under child entities.' It gives clear context for the appropriate scenario. However, it does not explicitly mention alternatives or 'when not to use' cases, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds valuable context about what the tool captures (standing alert status and specific firms currently listed), which deepens the agent's understanding 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, each earning its place: the first lists search capabilities, the second provides strategic context. No 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?

Although there is no output schema, the description gives an overview of the tool's purpose and hints at the returned entities ('specific firms currently listed under each alert'). Combined with the rich parameter descriptions, this is sufficient for a read-only search tool, though it doesn't describe pagination or result 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?

All 9 parameters have descriptions in the input schema, providing 100% coverage. The description's list of search fields doesn't add detail beyond what the schema already provides, so the baseline 3 applies here.

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

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

The description uses a specific verb ('Search') and resource ('FDA Import Alerts') and enumerates the search dimensions (firm, alert number, red-list vs green-list status, country, keyword, date). It also contrasts this with one-off import refusals, effectively differentiating it from the sibling tool fda_import_refusals.

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 second sentence explicitly positions this tool as a stronger manufacturing/supplier-risk signal than one-off import refusals, implying when to prefer it. While it doesn't name fda_import_refusals explicitly, the reference is clear enough, though it could go further by stating when to use the alternative.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not restate safety. It adds value by disclosing the return field set (labeler name, brand name, generic name, etc.) and the FEI linkage caveat, which informs expected behavior. It does not mention pagination quirks or rate limits, but these are largely covered by the schema and annotations.

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

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

The description is three sentences, each earning its place: the first states the action and search keys, the second lists return fields, and the third provides a critical caveat and related-tool pointers. It is front-loaded with the primary purpose and contains no redundant phrasing.

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

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

Despite lacking an output schema, the description enumerates the return fields clearly and provides usage context (e.g., the FEI caveat) and tool differentiation. It covers the essential information an agent needs to select and invoke the tool correctly, including related tools for adjacent use cases.

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

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

The input schema has 100% coverage, with each parameter having a descriptive name and a short description. The tool description does not add extra semantics beyond what the schema already provides; it merely lists the searchable fields (company, brand name, product NDC, application number) that correspond to parameters. 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 function: 'Search the National Drug Code (NDC) directory by labeler company, brand name, product NDC, or application number.' It uses a specific verb ('Search') and resource ('NDC directory'), and distinguishes itself from siblings by listing return fields and naming related tools for other data types.

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

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

The description provides explicit guidance: it notes that drug products are not linked by FEI and recommends using the tool with company name to find drugs at a company. It also names related tools (fda_search_drugs, fda_drug_labels, fda_search_nsde) with their purposes, effectively telling the agent when to choose an alternative.

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

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

Annotations already declare readOnlyHint and idempotentHint, which cover mutability. The description adds value by specifying the exact return fields (proprietary name, active ingredients, dosage form, route, marketing information), which is beyond what the input schema provides. No contradictions with annotations.

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

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

The description is concise and front-loaded: the first sentence states the core purpose, the second lists return fields, and the third names related tools. Every sentence contributes meaningful information with no repetition or filler.

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

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

The description covers the essential aspects: what is searched, by which fields, and what is returned. It also points to related tools. With no output schema, it does not describe the response structure, but the listed return fields and the input schema's pagination parameters provide adequate context 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?

The input schema has 100% description coverage, so the description adds little beyond what the schema already states. It lists the search fields (brand/proprietary name, application number, package NDC) but does not provide additional format or syntax details beyond the schema's own parameter descriptions.

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

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

The description clearly states the tool's function: searching the NSDE database by brand/proprietary name, application number, or package NDC. It names the resource (NSDE database), the search fields, and lists the return fields (proprietary name, active ingredients, dosage form, route, marketing info). It also distinguishes itself from related tools by naming them and their purposes.

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

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

The description mentions related tools (fda_search_ndc for NDC directory, fda_search_drugs for Drugs@FDA application data), giving clear context that these are alternatives. However, it does not provide explicit criteria for when to choose this tool over those alternatives, so it lacks the 'when-not-to-use' specificity required for a 5.

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

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

Annotations already indicate read-only and idempotent behavior, so the bar is lower. The description adds valuable context by disclosing that results are official FDA document-index metadata with direct links to posted records, and that extracted document text is included incrementally when available. It 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?

The description is two sentences, front-loaded with the core purpose and filters, followed by a concise statement about the content and use case. Every sentence earns its place with no wordiness or repetition of schema details.

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

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

For a search tool with 11 parameters and no output schema, the description communicates the essential purpose, filterable attributes, and the value proposition (links + extracted text). It could be more explicit about ordering (e.g., 'recent' implies date ordering) or default behavior, but the description is sufficiently complete for a typical search tool.

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

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

The input schema has 100% coverage, so the baseline is 3. The description briefly lists some filter fields (company, FEI, record type, country, establishment type, publish date) but does not add any meaning beyond what the schema already provides for parameters. It does not compensate with extra detail, so a 3 is appropriate.

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

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

The description uses a specific verb ('Search') and clearly identifies the resource ('FDA Office of Inspections and Investigations reading-room records'), listing several searchable fields. It distinguishes itself from sibling tools by naming OII reading-room records and noting the 483-style inspection evidence focus, which sets it apart from general inspection or warning letter searches.

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

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

The description provides clear context for use ('useful for finding recent 483-style inspection evidence by account') and implies a search/filter role. However, it does not explicitly state when not to use this tool or mention alternatives among the many sibling FDA tools, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds a useful caveat that keyword search works only 'when available' in extracted text, but it does not disclose response shape or further behavioral constraints. 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 two sentences: the first states the core purpose, the second lists the facets available. It is front-loaded, concise, and every sentence contributes useful information 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?

With no output schema, the description covers the data source and all major filter dimensions, including a caveat about keyword text availability. It does not explain pagination or return fields, but the schema already documents limit/offset and the search intent is clear, making it reasonably complete for a read-only search tool.

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

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

The input schema has 100% coverage with descriptions for all 8 parameters. The description restates the filter categories in natural language, but adds no semantic details beyond what the schema already provides, so it receives the baseline score.

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

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

The description uses a specific verb ('Search') and names a precise resource ('official FDA OPDP untitled letters') with a clear domain ('pharmaceutical promotion and advertising issues'). This clearly distinguishes it from sibling tools like fda_search_warning_letters.

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

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

The description provides clear context by enumerating filter dimensions (company, product, issue date, close-out availability, keyword), which implies when it is useful. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of full guidance.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral details: fuzzy company matching, date-range filtering, and the specific fields returned (PMA number, applicant, trade name, decision date, product code). 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?

Three sentences, front-loaded with the core action, then key filters, return fields, and related tools. No wasted words; each sentence earns its place.

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

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

The description fully covers a search tool: it states scope, provides regulatory context, lists all relevant filters, names return fields, and points to related tools. With good annotations and full schema, nothing essential is missing.

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

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

Schema coverage is 100% with clear descriptions for all 6 parameters. The description reiterates 'company name (fuzzy match), product code, and date range' but does not add substantial new meaning beyond the schema. Baseline 3 is appropriate since the 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 opens with a specific verb+resource+scope: 'Search FDA Pre-Market Approval (PMA) records across all companies.' It clearly distinguishes this from siblings like fda_search_510k by naming PMA and its high-risk (Class III) context, and explicitly lists related tools.

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

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

It explicitly states when to use PMA ('high-risk (Class III) devices') and points to fda_search_510k for lower-risk devices. It also names fda_device_class and fda_product_code_lookup as complementary lookups, giving clear alternatives and context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral context beyond annotations: it uses PostgreSQL text search, supports multi-word relevance ranking, and can be filtered by classification, product_type, or date range. It does not describe the return format or pagination details, but given the strong annotation coverage, this is sufficient.

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, front-loaded with the main purpose, and includes a helpful examples clause and related tools in a compact format. Every sentence earns its place; no 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?

For a tool with 8 parameters and no output schema, the description covers the search behavior, ranking, filters, and related tools. It doesn't explicitly state the return structure, but the absence of an output schema makes that less critical. The description is sufficiently complete for an agent to understand the tool's role and 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?

Input schema coverage is 100% with descriptive parameter properties, so baseline is 3. The description adds some context by mentioning filters (classification, product_type, date range) and giving example queries, but these largely mirror the schema. No additional parameter meaning is provided beyond what the schema already documents.

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

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

The description clearly states the tool performs full-text search across recall reasons and product descriptions, using PostgreSQL text search. It specifies the resource (FDA recall data) and the verb (search/find), and distinguishes itself from related tools by naming fda_search_enforcement (search by company name, classification, status) and fda_recall_facility_trace (trace to manufacturing facility).

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 related tools with their distinctive search capabilities, helping an agent choose between this and alternatives. It implies this tool is for semantic/text-based searches over recall text, while naming other tools for company-name or facility-trace use cases. It lacks a direct 'use when...' phrasing but is nevertheless 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?

Even with annotations indicating read-only/idempotent behavior, the description adds meaningful behavioral detail: it discloses that letter_category and violation_theme are best-effort heuristics, that status is derived from response/closeout dates, and that keyword cannot be scoped to a parsed cited-violations sub-section. It also explains the dedupe collapse behavior, going well beyond the annotation hints.

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

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

The description is information-dense but every sentence serves a purpose: stating the core function, listing filter capabilities, explaining derived fields and dedupe, providing cross-tool navigation, and setting expectations about heuristic limitations. The key search behavior is front-loaded, and the structure is logical.

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 14 parameters and no output schema, the description is remarkably complete. It tells users what each returned row contains (derived status, letter_category, fei_number for one-hop navigation), explains the heuristic nature of certain fields, and explicitly notes a limitation of keyword search. This fully compensates for the absence of an output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description significantly enhances parameter understanding by explaining how derived parameters (status, letter_category, violation_theme) are computed from other fields. It also clarifies the purpose of dedupe and fei_number for navigation, adding meaning not present 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 tool searches official FDA warning letters with full-text content, using a specific verb ('Search') and resource ('warning letters'). It also distinguishes itself from sibling tools by noting it 'adds narrative context beyond fda_compliance_actions, which only contains dashboard metadata.'

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

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

The description explicitly tells users when to use keyword search versus filters ('Use keyword search for the actual letter body, or filter by...'), advises setting dedupe=true for prospecting, and contrasts with the alternative fda_compliance_actions. This gives clear usage 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 and idempotentHint. Description adds behavioral details about exact vs fuzzy matching and the specific return fields (substance name, UNII, class, formula). It does not mention pagination behavior, but schema covers limit/offset.

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, front-loaded with the primary purpose, no redundancy with schema or annotations.

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

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

For a simple lookup with rich annotations and fully documented parameters, the description covers the use case, match types, and return fields. Minor gap: 'related details' is vague, and there is no output schema, but this is acceptable for this tool.

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

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

All 4 parameters have schema descriptions (100% coverage), so baseline is 3. Description reinforces the exact/fuzzy distinction already present in the schema but adds no new syntax or format details for 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?

Description uses specific verb 'look up' + resource 'FDA substance data', specifies exact vs fuzzy matching, and distinguishes from sibling tools by referencing UNII code. It also states the intended use case ('identify active pharmaceutical ingredients').

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 a clear use case ('Use to identify active pharmaceutical ingredients') and specifies lookup by UNII or name. However, it doesn't explicitly contrast with alternative FDA lookup tools or state when not to use this tool.

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

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

The description adds substantial context beyond the annotations (readOnly, openWorld, idempotent): it states the 2-credit cost, enumerates the return payload (FDA candidates, EDGAR, GLEIF, aliases, facility coverage stats), explains the meaning of coverage.unlinked_feis, and discloses the conservative, explainable validation workflow. This exceeds what the annotations convey.

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

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

The description is well-structured and information-dense: it opens with the core purpose, then covers cost, return items, a key metric, a caveat about external sources, and a recommended workflow. Every sentence adds value, and the workflow list improves scannability without padding.

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 having no output schema, the description fully compensates by listing the return categories, explaining an important field, and giving usage context. It covers cost, limitations, and follow-up tools, making it comprehensive for a tool with only two parameters and no output schema.

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

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

Schema coverage is 100%: both 'company' and 'cik' already have descriptive text. The description does not add further parameter-specific details beyond the schema, but it does mention the auto-resolution of CIK in the schema. Baseline of 3 is appropriate given complete schema coverage.

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

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

The description begins with a specific verb and resource: 'Discover subsidiary and related company names' and explains the multi-source approach (FDA datasets, then SEC EDGAR and GLEIF). It clearly distinguishes itself from sibling tools by naming related tools like fda_link_subsidiaries and fda_save_aliases.

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

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

Provides explicit usage guidance: a numbered recommended workflow (fda_suggest_subsidiaries → fda_link_subsidiaries or fda_save_aliases → risk summary or family search), and clarifies when external sources may lag. It also contrasts with related tools, making it clear when to use this tool vs alternatives.

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

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

Annotations already declare read-only and idempotent behavior. The description adds that the tool returns reports with product details and health problems, but does not disclose pagination behavior or other operational constraints. This is adequate but not rich.

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 front-load the purpose and key search criteria, then mention date format and return content. Every word 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?

For a search tool with six optional parameters and no output schema, the description covers the core function, filters, date format, and return content. It gives sufficient expectations, though pagination details are left to the schema.

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

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

Schema description coverage is 100%, so the schema fully documents all six parameters. The description reinforces the purpose of product_type and health_problem but adds no syntax details beyond what the schema already provides.

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

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

The description clearly states the verb 'Search', the resource 'tobacco problem reports', and the key filters (product type, health problem, date range). It distinguishes this tool from other FDA search tools in the sibling list, which focus on different report types or regulatory actions.

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

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

The description implies when to use: when searching tobacco problem reports by product type or health symptom. It provides clear context but does not explicitly mention alternatives or exclusions relative to sibling search 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 disclose read-only and idempotent behavior. The description adds that it returns event reports with animal details, drug information, and adverse reactions, which is useful. However, it also mentions 'reaction' as a filterable criterion, but no such parameter exists in the schema, creating potential confusion about actual capabilities. This partial inaccuracy lowers the score.

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, front-loaded with the primary action, quickly summarizes return contents, and appropriately references a related tool. No wasted words.

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

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

For a search tool with 7 parameters and no output schema, the description gives a broad overview of filters and return contents, which is decent. However, it omits that 'reaction' is not a supported filter, and it does not mention default limit or pagination behavior (though these are in the schema). The misleading 'reaction' mention creates a gap in 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?

The schema provides 100% coverage of parameters with descriptions. The description adds a high-level grouping of filter types (species, drug name, serious flag, date range) but introduces a 'reaction' filter that is not present in the schema, diminishing its value. Baseline is 3 because schema already 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 function: 'Search veterinary adverse events (animal drug safety reports)' with a specific verb and resource. It enumerates the main filter categories and explicitly distinguishes itself from the related sibling fda_search_aphis, making its purpose unambiguous.

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

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

The description provides clear context on what the tool searches for (species, drug name, serious flag, date range) and mentions a related tool for veterinary biologics facilities, implying when to choose this tool over that alternative. However, it stops short of an explicit 'use this when you need X' or 'do not use for Y' statement.

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