openfda

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

Annotations only declare readOnlyHint=true, so the description carries the rest. It discloses the return shape (a term/count histogram rather than records), the '.exact' whole-phrase behavior, and that limit caps distinct terms — genuinely useful behavioral context beyond the annotation.

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

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

Front-loaded with the core behavior, then the '.exact' rule, then a concrete example. The 'openFDA's most valuable feature' framing is mildly promotional, but the rest is dense 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?

With no output schema, the description compensates by describing the return structure (`results: [{term, count}]`) and the aggregation semantics. Enough for an agent to call it correctly, though pagination/ordering of top terms is not addressed.

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 all four parameters are already documented. The description reinforces the '.exact' suffix convention and gives a search/endpoint/field example, but adds little that the schema does not already state, so the baseline 3 applies.

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

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

States a specific verb and output: aggregate over a dataset by a field to get a top-terms histogram, returning `results: [{term, count}]` instead of records. This clearly distinguishes it from the sibling search_* tools, which return records.

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

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

Explains the concrete usage pattern (aggregate by field, optionally prefixed with a Lucene search filter) and includes a worked example. It implies the when-to-use case versus the search tools by contrast, but never explicitly names a sibling or states 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, so the safe-read profile is covered, and the description adds that it exposes the full parameter set and spans the whole API surface. However, for an openFDA tool it omits operationally relevant traits such as rate limits / API-key requirements and the practical paging ceiling behavior. Adds some value, but not rich behavioral context.

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

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

Two front-loaded sentences that put the scope claim and the routing rule first, with no padding. The trailing fragment 'openFDA REST API.' is a minor dangling stub rather than earned content.

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

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

For a 6-parameter generic tool with a fully documented schema and no annotations beyond readOnly, the description supplies the scope and routing an agent needs. Return-shape details are unnecessary without an output schema, though the omitted rate-limit caveat keeps it short of complete.

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

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

Schema coverage is 100%, so every parameter (search, sort, count, limit, skip, endpoint) is already documented in the schema, and the description adds no syntax or format detail beyond it. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

The description states a specific verb+resource ('query ANY supported openFDA endpoint') and explicitly frames itself as the generic escape hatch covering less-common datasets. It names concrete examples (device/pma, device/udi, drug/orangebook, tobacco/problem) and contrasts with the named search tools, so an agent can distinguish it from all siblings.

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

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

It gives explicit routing rules: use the named search tools for common datasets, use this one for everything else or for advanced queries. That is a clear when-to-use / when-not-to-use split with an alternative named.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read. The description adds the dataset provenance ('openFDA device/510k endpoint') and enumerates returned fields, which is useful context, but says nothing about pagination behavior, rate limits, or result truncation. With annotations covering safety, a 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?

Two sentences, front-loaded with the resource, then the domain explanation and data source. No wasted words, though the field enumeration ('applicant, decision, product code and dates') is slightly list-like filler for a search tool.

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

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

For a simple read-only search tool with a fully documented schema, no output schema, and readOnlyHint covering the safety profile, the description is adequate. It partially compensates for the missing output schema by indicating which fields the records carry, but does not describe result shape or pagination limits.

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 skip, sort, limit, and the Lucene-style search syntax are all fully documented in the schema. The description adds no parameter-level detail beyond that, so the baseline 3 is correct.

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

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

States a specific verb (Search) and a well-defined resource (510(k) premarket notification clearances), and explains what a 510(k) clearance means ('devices cleared for market as substantially equivalent to a predicate'), which is genuinely clarifying domain context. It does not explicitly differentiate itself from device siblings like search_device_classification or search_device_events, but the resource is distinctive enough that an agent can tell them apart.

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

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

No guidance on when to use this tool versus alternatives such as search_device_classification, and no mention of prerequisites or expected query context. Usage is only implied by the resource name.

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 readOnlyHint annotation already tells the agent this is a non-destructive read, so the description's main added value is the identity of the backing endpoint and the shape of returned classification records. It does not disclose pagination limits, result caps, or rate-limit behavior beyond what the schema's skip/limit fields already say, so it clears the lower bar set by annotations but adds only modest behavioral context.

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

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

Two tightly packed sentences: the first front-loads what the tool returns, the second identifies the endpoint. No filler, no repetition of the title, and the most useful information (returned fields) comes first.

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 usefully enumerates the return fields and identifies the data source, and annotations cover the safety profile. It is close to sufficient for a read-only search tool, though it could say more about result shape or pagination interplay between skip and limit at the described ~26000 record ceiling.

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% — skip, sort, limit and search are all documented in the schema, including the Lucene query syntax and limits. The description mentions the searchable classification fields implicitly but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

Names a specific verb (Search) and a specific resource (the FDA device classification database), and enumerates exactly what a record contains: product code, device class I/II/III, regulation number, medical specialty and submission requirements. The dataset is named so precisely that an agent can distinguish it from sibling searches over device 510k, events, and recalls without opening any schema.

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 scopes the tool to a dataset (and names the underlying openFDA endpoint), which implies when it applies, but it never states when to prefer it over the sibling search tools such as search_device_510k or search_device_events, nor any exclusions. Usage is inferable from the resource name rather than stated.

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, so the safety profile is covered by structured data. The description adds the semantic content of the dataset (injuries, deaths, malfunctions) and the underlying endpoint, but says nothing about rate limits, pagination ceilings, or result shape beyond what the schema implies.

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 short fragments with the substantive content (dataset and subject matter) front-loaded and no filler. The trailing 'openFDA device/event endpoint' is mildly redundant but is genuinely useful for mapping to the API docs.

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 should ideally hint at return format or result interpretation, and it does not. Parameters are exhaustively covered by the schema and read-only safety is covered by annotations, so the tool is callable, but the description leaves gaps around output behavior.

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

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

Schema description coverage is 100%, so skip/sort/limit/search are already fully documented, including Lucene syntax and range examples. The description contributes no additional parameter meaning, which matches the baseline 3 when the schema does all the work.

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

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

States a specific verb ('Search') plus the exact resource ('MAUDE database: medical device adverse events — injuries, deaths, malfunctions') and names the underlying endpoint. An agent can distinguish this from siblings like search_device_recalls or search_drug_events purely from the resource scope.

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 identifies what dataset it queries but never states when to choose it over alternatives such as count or openfda_query, nor does it mention prerequisites, expected use cases, or exclusions. Usage is only implied by the resource name.

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?

readOnlyHint=true already tells the agent this is a safe read, so extra behavioral disclosure is not strictly required. The description adds the enumerated result fields, which is useful because no output schema exists, but it says nothing about result caps, truncation, or pagination behavior (the schema's ~26k ceiling only shows up in the parameter docs).

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

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

Two tight clauses with the purpose front-loaded; the field enumeration is dense but informative. The trailing 'openFDA device/recall endpoint' sentence is mildly redundant with the tool name, keeping it from a full 5.

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, listing the returned fields is exactly the right compensation, and the schema fully covers query syntax and pagination. What is missing is any note on result limits/responses when the query matches nothing or exceeds the documented ceiling, but overall it is sufficient to call the tool correctly.

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

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

Schema description coverage is 100% and all four parameters (skip, sort, limit, search) are documented thoroughly in the schema, including Lucene syntax, ranges, and pagination limits. The description contributes no additional parameter semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('Search medical device recalls') and enumerates the returned data (reason, recalling firm, classification, product code, status), which scopes it apart from search_drug_recalls, search_food_recalls, and search_device_events. It stops short of explicitly naming those siblings as alternatives, so the differentiation remains implicit via the dataset name.

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?

There is no when-to-use guidance, no exclusions, and no routing to alternatives such as count for totals or openfda_query for cross-dataset queries. The only usage hint is the provenance note 'openFDA device/recall endpoint', which identifies the source but not the conditions under which an agent should pick 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, so the safety profile is covered. The description adds useful context that this returns individual case reports rather than aggregates and that it maps to the openFDA drug/event endpoint, but says nothing about pagination limits, rate limits, or result ordering 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?

Front-loaded with the core action and dataset, no filler sentences, and short enough to scan quickly. The trailing 'openFDA drug/event endpoint.' fragment is slightly tacked-on but still informative.

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

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

With no output schema, the description correctly notes that individual case reports are returned, and pagination/query mechanics are fully documented in the schema. What is missing is usage context relative to sibling search tools, which would help an agent route correctly.

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

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

Schema coverage is 100% with no required parameters, so the schema already documents skip, sort, limit, and the Lucene query syntax in detail. The description contributes nothing about parameter semantics beyond the dataset name. Baseline 3 applies.

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

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

States a specific verb (Search) and a precisely scoped resource (FDA Adverse Event Reporting System reports of side effects, adverse reactions, medication errors), and names the underlying openFDA endpoint. This is clearly distinct from the sibling searches for labels, recalls, NDC, and Drugs@FDA.

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

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

The description explains what the dataset contains but gives no explicit when-to-use guidance, no prerequisites, and never names an alternative (e.g., search_drug_labels or search_drug_recalls) or the condition that would select one over this tool. Usage must be inferred from the name alone.

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

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

readOnlyHint=true already establishes this is a safe read, and the description adds the data-source/endpoint context (openFDA drug/label). It does not disclose return shape, rate limits, or result-shaping behavior, so it goes modestly beyond the annotation but not richly.

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 that front-loads the verb and resource before the enumerated contents. Every clause earns its place, though the em-dash list makes it slightly run-on rather than crisp.

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, zero-required-parameter search tool with no output schema, the description usefully signals what the returned labels contain, which partially compensates for the missing output schema. It omits nothing essential for correct invocation, though return-format guidance is absent.

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 skip, sort, limit, and search are all documented in the schema itself, including Lucene syntax and range examples. The description adds nothing parameter-specific, making the baseline 3 correct.

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

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

States a specific verb+resource ('Search Structured Product Labeling (SPL)') and spells out what SPL contains — indications, warnings, dosage, adverse reactions, interactions — which cleanly separates it from siblings like search_drug_ndc, search_drug_events, and search_drug_recalls. The openFDA endpoint reference anchors it further.

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 conveys what kind of data lives here, which implicitly tells an agent when to reach for it, but there is no explicit when-to-use vs. alternative or any exclusion guidance against the many sibling search_* tools. Usage is inferred, not stated.

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 readOnlyHint annotation already establishes this is a safe read. The description adds useful context by listing what a record contains and naming the underlying openFDA data source, but says nothing about result limits, pagination semantics, or rate limiting beyond what the schema already conveys.

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 compact sentences, front-loaded with the verb and dataset, with the field enumeration and data source appended. No wasted prose, though the field list is somewhat dense.

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 fields a record contains. Annotations cover the safety profile and the schema fully documents parameters, so the agent has enough to call it correctly; only usage routing remains thin.

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 all four parameters (skip, sort, limit, search) are fully documented in the schema. The description adds no parameter-level detail, so baseline 3 is appropriate.

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

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

States a specific verb (Search) and resource (the National Drug Code directory) and enumerates the exact fields of the dataset (code, name, dosage form, route, active ingredients, marketing status, labeler). This clearly differentiates it from the many sibling search_* tools targeting drug events, labels, recalls, drugsfda, etc.

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

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

The description says what the tool searches but never says when to choose it over the numerous sibling tools (e.g., search_drug_labels vs search_drugsfda vs search_drug_ndc). No alternatives, no conditions, no prerequisites are given.

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, so the safety profile is covered externally. The description adds useful context by naming the backing endpoint (openFDA drug/enforcement) and the fields returned, but says nothing about result caps, pagination limits, or rate limiting beyond what the schema states.

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: the first front-loads purpose and the returned content, the second pins the data source. No filler or restated title 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?

With no output schema, the description usefully enumerates the fields each recall record carries, so an agent knows what comes back. Only minor gaps remain, such as default result behavior and pagination limits, which the schema's parameter text already handles.

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 skip, sort, limit, and search are fully documented in the schema itself, including Lucene syntax and range examples. The description adds no parameter-level meaning beyond that, so the 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?

Specific verb (Search) plus a precisely scoped resource (drug recall enforcement reports), and it enumerates what each report contains (reason, classification Class I/II/III, recalling firm, distribution, status). The 'drug' qualifier and the 'drug/enforcement endpoint' note clearly separate it from sibling recall tools like search_device_recalls and search_food_recalls.

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 drug-specific framing implies when this tool applies versus the device/food recall siblings, but there is no explicit when-to-use, when-not, or reference to alternatives such as openfda_query or count for aggregate questions. Usage is inferable but never stated.

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, so the safe-read nature is covered by structured data. The description adds only the endpoint mapping ('openFDA drug/drugsfda endpoint') and dataset identity; it says nothing about pagination limits, default result count, or rate limiting beyond what the schema already states.

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 compact sentences with the dataset scope front-loaded and no wasted clauses. The trailing endpoint reference is mildly redundant but still informative for an agent mapping to the openFDA API.

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 should ideally hint at the return shape (nested applications/products/submissions arrays), which it only lists obliquely. It covers dataset scope adequately but leaves result-structure and pagination semantics to the schema, which is workable but incomplete.

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 skip, sort, limit, and the Lucene search syntax with an example. The description contributes no additional parameter meaning, making the baseline 3 appropriate.

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

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

The description names a specific verb (Search) and resource (Drugs@FDA: FDA-approved drug products and their applications/NDA/ANDA/BLA, sponsors, approval dates, products, submissions). This clearly distinguishes it from sibling datasets like search_drug_events, search_drug_labels, and search_drug_ndc, though it never names those siblings explicitly.

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?

Usage is only implied by the dataset scope: an agent can infer this is for drug approval/application data, but the description gives no explicit when-to-use guidance, no when-not-to-use, and no pointer to alternatives such as search_drug_events or search_drug_labels. Adequate but with a clear gap.

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, so the agent knows this is a non-mutating read. The description adds useful scope context (both current and resolved records, and the fields returned), but says nothing about result volume, rate limits, or pagination behavior that isn't already in the 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?

Two tight sentences with zero filler; the dataset scope leads and the endpoint reference trails as a compact identifier.

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 fully documented parameters, readOnlyHint annotations, and no output schema, the description covers what is searched and what fields come back. Only minor gaps remain, such as expected result volumes or default behavior when no query is supplied.

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 skip, limit, sort, and search all thoroughly documented in the schema itself, so the baseline is 3. The description contributes no additional parameter syntax or formatting guidance beyond what the schema provides.

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

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

The description names a specific verb+resource ('Search current and resolved drug shortages') and enumerates the returned facets (product, status, reason, availability, dates), plus cites the underlying openFDA drug/shortages endpoint. It is clearly distinguishable from most siblings, though it does not explicitly contrast with the generic openfda_query or count 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 phrase 'current and resolved' implies that both active and historical shortages are covered, but there is no statement of when to prefer this tool over openfda_query, count, or the other search_* siblings, and no prerequisites or exclusions are given.

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, so the safety profile is covered by structured data. The description adds useful provenance (CAERS dataset, openFDA food/event endpoint) but says nothing about rate limits, result caps beyond the schema, or what a returned record contains.

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 short sentences with the dataset identity front-loaded and essentially no filler. Minor redundancy in closing with the raw 'openFDA food/event endpoint' label after already naming CAERS, but overall tight.

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 readOnlyHint and fully documented parameters, an agent has what it needs to call this safely and correctly. No output schema exists, so return-value description isn't required, though a hint that a companion count tool exists for totals would complete the picture.

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 explains skip/limit/sort/search syntax in detail, including Lucene operators and ranges. The description adds no parameter-level meaning beyond what the schema provides, making the baseline 3 correct.

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?

Names a specific verb (Search) and a precisely scoped resource: CAERS adverse events and product complaints for foods, dietary supplements and cosmetics. This cleanly distinguishes it from siblings like search_drug_events and search_device_events without needing to open any schema.

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 dataset scoping (food/dietary supplement/cosmetic adverse events) implies when this tool applies versus the drug or device event siblings, but the description never states usage conditions or exclusions explicitly. Also silent on the sibling 'count' tool for aggregations.

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?

readOnlyHint=true already tells the agent this is a safe read, so the safety profile is covered. The description adds the upstream source (openFDA food/enforcement endpoint), which is mildly useful context, but it says nothing about rate limits, result caps, or pagination behavior that the schema does not already cover.

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?

It is a single tight sentence (plus a short source clause) with the resource and its contents front-loaded. Nothing is wasted, though the trailing endpoint mention is the weakest element.

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 100% schema coverage and annotations covering safety, the definition is essentially sufficient: the agent knows the domain, and the searchable field inventory. Only the missing sibling routing keeps it from being fully complete.

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

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

Schema description coverage is 100%, so the schema already fully documents skip, sort, limit and the Lucene search syntax. The description contributes no additional parameter meaning, which is the correct baseline of 3 when structured fields carry 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 states a specific verb (search) and resource (food recall enforcement reports) and enumerates the record contents (reason, classification, recalling firm, distribution state, status). It is clearly distinguishable from search_food_events, but it does not explicitly contrast itself with the parallel search_drug_recalls / search_device_recalls siblings, so the 'food' domain is the only differentiator.

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?

There is no when-to-use guidance, no statement of when another recall tool is more appropriate, and no prerequisites or constraints mentioned. The reader must infer usage purely from the tool name and the domain keyword.

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