openFDA MCP by usefulapi

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

Annotations only declare readOnlyHint=true, so the description carries real weight: it discloses the return shape (aggregated terms rather than records), that 'search' is applied before aggregation, and the token-vs-phrase behavior of '.exact'. It omits rate limits, result ordering, and pagination, which keeps it out of the top band.

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-loads the core insight ('aggregate... top-terms histogram') before the example, and every sentence is load-bearing. The worked example is slightly verbose but earns its place by demonstrating the parameter combination.

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 4-parameter aggregation tool with no output schema, the description compensates by describing the return shape and the pre-aggregation filter behavior. It could still note result ordering or limits interplay, but nothing essential for a correct call 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%, so baseline is 3, but the description adds genuine value by showing how endpoint, field, and search combine in a concrete example, and by explaining the semantic effect of the '.exact' suffix. This is integration guidance the schema alone does not convey.

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 ('aggregate over any dataset by a field to get a top-terms histogram') and explicitly contrasts the output with the sibling search tools ('returns results: [{term, count}] instead of records'). An agent can immediately tell this apart from the search_* 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?

Gives a clear use case and a worked example wiring endpoint, field, and search together, plus the '.exact' rule for phrase counting. It implies but never explicitly states when to prefer this over the named sibling search tools (e.g. 'use search_drug_events when you need records'), so it stops short of full routing 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?

readOnlyHint=true already tells the agent this is a safe read, so the safety burden is carried. The description adds useful scope context ('full parameter set', advanced queries) but says nothing about openFDA rate limits or API-key requirements, and the pagination caps are left to 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?

Three front-loaded sentences that lead with the tool's role and then give routing guidance. The long parenthetical list of endpoints duplicates the enum in the schema, which is mild redundancy, but it aids scanability and doesn't bury the key message.

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

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

Covers the essential facts for a generic multi-endpoint query tool: what it covers, when to prefer it, and that it's a raw REST wrapper. With no output schema, it could say more about the shared response envelope, but endpoint-specific output is inherently variable and the usage picture is complete.

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

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

Schema description coverage is 100%, so every parameter is already documented with format detail (Lucene syntax, skip/limit ranges, sort syntax). The description adds only the phrase 'full parameter set' without any format or constraint detail, 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?

States a specific verb+resource ('query ANY supported openFDA endpoint') and immediately frames its role as a 'generic escape hatch' versus the named search tools. An agent can tell exactly what it does and where it sits relative to siblings without opening the 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?

Explicit routing rules: use this for less-common datasets or advanced queries, use the named search tools for common datasets. It even enumerates which datasets fall on the 'less-common' side (device/pma, drug/orangebook, tobacco/problem, etc.), so when-to-use and when-not-to-use are both 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 read-only safety profile is covered. The description adds the result-content context (applicant, decision, product code and dates) and names the underlying endpoint, but says nothing about pagination ceilings, default limit behavior, or result stability.

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?

One front-loaded sentence naming the verb, resource, record contents, and data source. The trailing 'openFDA device/510k endpoint' fragment is mildly redundant but not wasteful.

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

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

For a read-only search tool with no output schema, the description usefully enumerates the fields returned, partially substituting for a missing return contract. Combined with fully documented parameters, an agent has enough to call it correctly, though pagination behavior is 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%, with each of the four parameters documented in the schema itself, including the Lucene syntax and pagination bounds. The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (search) and resource (510(k) premarket notification clearances) and clarifies what these records represent — devices cleared as substantially equivalent to a predicate. This distinguishes it cleanly from siblings like search_device_classification, search_device_events, and search_device_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 resource specificity implies when the tool applies, but there is no explicit when-to-use or when-not-to-use guidance, and no routing to sibling search tools despite a large family of device search endpoints being available.

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. The description adds useful provenance ('openFDA device/classification endpoint') and the shape of returned records, but says nothing about pagination limits, rate limits, or result envelope behavior beyond what the schema documents.

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?

One compact sentence with no filler: purpose first, returned fields second, data-source provenance last. Every clause carries information and nothing is redundant with the title.

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 full schema coverage and no output schema, the description supplies the key missing piece: what fields a result record contains. It stops short of describing the openFDA results/meta envelope, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so all four parameters (skip, sort, limit, search) are already fully documented in the schema, including Lucene syntax and range examples. The description adds no parameter-level meaning beyond that, 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?

Opens with a specific verb+resource ('Search the FDA device classification database') and enumerates the domain it returns: product code, device class, regulation number, specialty, submission requirements. This clearly separates it from siblings like search_device_510k, search_device_events and search_device_recalls, which cover different device 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 dataset scope implies when the tool is relevant (looking up a device type's class/regulation), but there is no explicit when-to-use, no when-not-to-use, and no pointer to alternatives such as count, openfda_query, or the other search_* siblings. Usage is inferable but 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?

With readOnlyHint=true the annotations already establish the safety profile, so the description only needs to add context. It does add useful coverage context (the endpoint is device/event and the records are adverse-event reports), but it says nothing about rate limits, authentication, or result caps.

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 with the resource front-loaded. Slightly redundant phrasing — 'medical device adverse events' followed by 'malfunctions involving medical devices' — costs it the top mark.

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 full schema coverage, the description covers what data is being queried. With no output schema, it does not describe the shape of returned reports, which is the main remaining gap, along with no hint about sibling routing.

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 (skip, limit, sort, search) are already documented in the schema, including Lucene syntax and pagination ceilings. The description adds no parameter detail, 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 gives a specific verb (Search) and a precise resource (the MAUDE database / openFDA device/event endpoint), and it enumerates the data content — reported injuries, deaths, and malfunctions involving medical devices. That domain naming alone separates it cleanly from siblings like search_drug_events or search_food_events.

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 at all: no mention of when this beats count or openfda_query, no pagination strategy, no note about when to prefer it over search_device_recalls or search_device_510k. The agent must infer usage purely from the name and domain.

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 declares this a safe read, so the bar is lower. The description adds provenance ('openFDA device/recall endpoint') and the shape of returned records, but says nothing about rate limits, API-key behavior, or pagination ceilings that a search client would care about.

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 clauses, front-loaded with the verb and resource, with no redundant restatement of the title. The trailing endpoint fragment is terse but earns its place as provenance.

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 usefully enumerates the returned fields in place of a return-value contract, and the schema fully covers inputs. Only rate-limit and pagination caveats are absent, which is a minor gap.

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

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

Schema description coverage is 100% with four fully documented parameters, including Lucene syntax and range examples. The description adds no parameter-level meaning 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?

States a specific verb+resource ('Search medical device recalls') and enumerates the content surfaced (reason, recalling firm, classification, product code, status). The 'device' qualifier implicitly separates it from search_drug_recalls and search_food_recalls, but no sibling is named 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?

No when-to-use, when-not-to-use, or alternative routing is provided. It never mentions openfda_query or count as complementary tools, nor the conditions for paginating with skip/limit. Usage is left entirely to inference from the 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 establishes a safe read, so the bar is lower; the description usefully adds that the result set is individual case reports tied to the openFDA drug/event endpoint. It says nothing about openFDA rate limits, result volume, or what a case report 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?

Three short sentences, each earning its place: domain expansion, return granularity, and source endpoint. Nothing is repeated and no filler is present.

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

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

For a no-required-parameter search tool with no output schema and full schema coverage, the description covers purpose, data source, and return form adequately. Minor gaps remain around result volume/rate limits, but the agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the four parameters (skip, limit, sort, search) are fully documented in the schema itself, including Lucene syntax and pagination caps. The description adds no parameter-level meaning, which is acceptable given 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?

States a specific verb (Search) and a precisely named resource (FAERS adverse-event reports of drug side effects, reactions, medication errors), plus the underlying endpoint (openFDA drug/event). An agent can immediately separate this from search_drug_labels, search_drug_recalls, or search_device_events 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?

Usage is implied by the data domain but never stated: there is no guidance on when to choose this over siblings like count or openfda_query, nor any exclusion or prerequisite. The note that it 'Returns individual case reports' hints at the raw-record use case but does not route the agent explicitly.

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 the description adds only the data source (openFDA drug/label endpoint), which is context rather than behavior. Nothing is said about openFDA rate limits (notably restrictive without an API key), result caps, or throttling — the kind of operational detail that would justify a higher 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?

Two compact clauses with zero waste; the resource and its contents are front-loaded and the data-source attribution is tacked on at the end. Nothing is redundant.

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?

Adequate for a search tool whose schema fully documents parameters and whose annotation covers safety, but with no output schema the description should say more about what a label result contains or which fields are searchable. Rate-limit and query-cost expectations are also 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 all four parameters (skip, sort, limit, search) are fully documented in the schema, including Lucene query syntax and pagination limits. The description contributes nothing beyond that, 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 (Search) and resource (Structured Product Labeling / openFDA drug/label) and enumerates the content scope — indications, warnings, dosage, adverse reactions, drug interactions. This content-level specificity implicitly separates it from siblings like search_drug_events and search_drug_ndc, though it never names an alternative.

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 when-to-use, when-not-to-use, or alternative tool is named. The reader must infer from the purpose statement that this is for label text rather than adverse events or NDC lookups; there is no routing guidance at all.

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

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

Annotations only declare readOnlyHint=true, so the safety profile is already carried by structured data. The description adds the backing endpoint ('openFDA drug/ndc endpoint'), which is mild context, but says nothing about pagination ceilings (the schema does), rate limits, or API-key requirements that openFDA callers should expect.

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, front-loaded with the resource and scope; the endpoint clause is the only marginal extra. No filler, no restatement of the title.

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 doubles as a return-value summary by enumerating the product attributes returned. Combined with 100% schema coverage and a readOnly annotation, the definition is close to complete; only guidance on alternatives and API constraints 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/limit/sort/search are fully documented in the schema itself. The description's field list gives a hint about which fields the Lucene query can target, but adds no query syntax or parameter detail beyond what the schema already provides.

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

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

States a specific verb and resource ('Search the National Drug Code (NDC) directory') and enumerates the content scope (code, name, dosage form, route, ingredients, marketing status, labeler). This field list implicitly separates it from siblings like search_drug_labels or search_drug_events, though it never explicitly contrasts them, so it stops short of a 5.

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 implied rather than stated: an agent can infer this is the tool for product/code-level lookup because the enumerated fields are all NDC product attributes. There is no explicit when-to-use, no exclusions, and no mention of which sibling to prefer for label text, adverse events, or recalls.

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, and the description adds the underlying endpoint and the shape of returned records. However, it omits notable openFDA behaviors such as rate limits, the fact that search is optional, and result-count semantics, so it only modestly exceeds 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?

Two compact clauses front-load the resource and the returned fields, with no redundant restatement of the title. The trailing endpoint tag is short and informative, so little is wasted.

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 enumeration of returned fields (reason, classification, firm, distribution, status) usefully stands in for a return-value description. Still, the description leaves gaps around rate limits, whether the query parameter is required for meaningful results, and total-result behavior for a 4-parameter 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 skip/limit/sort/search are fully documented in the schema and the baseline is 3. The description adds no syntax or format detail beyond the schema, though mentioning Class I/II/III hints at useful search field values.

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 the records contain (reason, Class I/II/III classification, recalling firm, distribution, status). This implicitly but clearly separates it from the sibling recall tools (search_device_recalls, 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 scope implies when to pick this over device/food recall siblings, but there is no explicit when-to-use, when-not, or routing guidance (e.g., versus count or openfda_query for aggregation). Usage is left to inference from the name and dataset scope.

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 the safe-read profile, so the description's main added value is identifying the backing dataset/endpoint. It does not disclose pagination ceilings, result caps, or rate-limit behavior beyond what the schema states, but it does not contradict anything.

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 zero filler, front-loaded with the dataset identity and followed by the endpoint reference. Nothing is redundant with the title or wasted on restating the name.

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 filter/search tool with no output schema, the description adequately conveys what corpus is searched and against which endpoint. It stops short of describing result shape or the practical impact of the limit/skip caps, but the 100%-covered schema carries that load.

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 (skip, sort, limit, search) are already fully documented, including the Lucene syntax and the unusual default limit of 1. The description adds no query syntax or field-hint 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?

The description names a specific verb ('Search') and a precisely scoped resource ('Drugs@FDA: FDA-approved drug products and their applications (NDA/ANDA/BLA), sponsors, approval dates, products and submissions'), plus the exact underlying endpoint. It cleanly separates this dataset from siblings like search_drug_labels, search_drug_events, and search_drug_ndc so an agent can route correctly.

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; there is no explicit 'use this when' statement, no prerequisites, and no named alternative (e.g., versus search_drug_labels or search_drug_ndc). An agent can infer the domain but must decide on its own when this is the right sibling.

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 declares this a safe read, so the description's marginal disclosure is limited to noting that resolved as well as current shortages are covered and which fields appear. It does not discuss pagination behavior or the result set shape, which the schema only partially covers.

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 resource and its coverage front-loaded and the endpoint noted last. 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?

With no output schema and minimal annotations (only readOnlyHint), the description usefully compensates by listing the returned fields, so an agent knows what a hit contains. The only gap is the absence of usage/routing and pagination context, minor for a well-documented search endpoint.

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, limit, sort and the Lucene-style search syntax are already fully documented in the schema. The description adds nothing beyond that, which is the expected baseline when the schema carries parameter meaning.

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

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

The description gives a specific verb (Search) plus the resource (drug shortages) and enumerates the substantive fields returned: product, status, reason, availability, dates. It also states the scope 'current and resolved,' which cleanly separates it from siblings like search_drug_recalls or search_drug_events without needing to read a 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 'current and resolved' scope implicitly tells the agent this is the shortage dataset, but there is no explicit when-to-use guidance, no prerequisites, and no routing to or away from sibling tools. Adequate but leaves selection vs. alternatives to inference.

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=true annotation already establishes this is a safe read, so the description only needs to add context — and it does add the data source and endpoint identity. It says nothing about pagination ceilings, result caps, or rate limiting, which are left to the schema's skip/limit descriptions.

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, zero filler, with the dataset identity front-loaded and the endpoint reference appended as a clarifying pointer. Nothing repeats the title or the 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 four-optional-parameter search wrapper with fully documented schema and a readOnly annotation, the description supplies enough to select and invoke it correctly; the lack of an output schema is not a gap since search results are self-describing. Only the missing sibling routing keeps it short of full 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?

Schema description coverage is 100%: skip, sort, limit and the Lucene 'search' syntax are all documented in the schema, including ranges, .exact phrases and date formats. The description adds no parameter detail beyond what the schema already supplies, 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?

The description names a specific verb (Search) and a precisely bounded resource: the CFSAN Adverse Event Reporting System covering foods, dietary supplements and cosmetics. It even names the backing endpoint ('openFDA food/event'), which distinguishes it from its nearest sibling search_food_recalls, which covers recalls rather than adverse events.

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 or when-not-to-use guidance and no routing to alternatives such as search_food_recalls, count or openfda_query. The agent must infer from the dataset name alone that this is the adverse-event dataset rather than the recall dataset.

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, so the bar is lower. The description adds useful context by naming the dataset and the fields available, but says nothing about openFDA rate limits, result caps, or pagination behavior that an agent should anticipate.

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 no filler; the core purpose is front-loaded before the endpoint reference. Every clause (fields returned, classification scheme, endpoint) contributes useful information.

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

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

For a read-only search tool with complete parameter documentation and no output schema, the description is sufficient to call it correctly and understand what is returned. The only gap is routing guidance against sibling search tools, which is minor here.

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

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

Schema description coverage is 100%, and the schema fully documents skip/limit/sort/search with syntax and examples, so the description carries no additional parameter burden. The field list loosely hints at searchable fields but adds nothing the schema does not already provide; 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?

The description states a specific verb ('Search') plus resource ('food recall enforcement reports') and enumerates the content returned (reason, classification, firm, distribution, status). It is clearly distinct from the drug/device recall siblings by domain, though that differentiation comes mainly from the name token rather than explicit contrast.

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 guidance on when to choose this tool over alternatives such as search_food_events (food adverse events) or the drug/device recall tools. The endpoint reference ('openFDA food/enforcement') identifies the source but does not tell an agent when this dataset is the right one to query.

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