PlainRecords: U.S. recalls in plain English

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: a hard cap of 25 records, inclusion of per-agency kinds and record/recall counts, and the edge case that an NHTSA-removed campaign still counts as a record — a nuance an agent otherwise could not guess.

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 record set and its breadth before the qualifiers. It is dense but every clause carries information; no filler sentences.

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

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

With no output schema, the description must carry the return shape, and it does: records with agency-provided kind labels plus aggregate counts of records and recalls. Enough for an agent to call it and interpret results, though matching semantics for the brand input remain unspecified.

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?

There is a single required parameter whose schema description coverage is 100%, so the baseline is 3. The description adds nothing about how the brand string is matched (exact vs fuzzy, aliases), so it neither compensates nor detracts.

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 the resource (recall records for a brand/company) and its scope (newest up to 25, across FDA, USDA FSIS, CPSC, NHTSA), which lets an agent separate it from siblings like vehicle_recalls or food_outbreaks. It never states an explicit verb, but the retrieval intent is 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?

Usage is only implied — the agent must infer that this is the tool for pulling a brand's recent recall history, and search_recalls is referenced only tangentially for date formatting rather than as a named alternative. No when-not-to-use guidance is 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 establish this is a read-only lookup (readOnlyHint), so the description need only add context; it does add a result cap ('up to 15') and a 'Not medical advice' caveat. It does not explain truncation behavior or what happens when more than 15 matches exist.

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 sentence carrying the match rule and returned fields, plus a short disclaimer. Front-loaded and free of filler, though the '(up to 15)' parenthetical interrupts the sentence flow slightly.

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

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

No output schema exists, so the description usefully names the returned fields (status, availability, reason, dosage form, update date). The only real gap is the unspecified behavior when the 15-entry cap is exceeded.

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

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

With schema coverage at 100% and a single parameter, the schema already documents the drug name input. The description's 'generic name contains the words given' adds substring-matching semantics that the schema's 'name or part of it' only weakly implies, so slight value beyond 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?

States a specific verb+resource: retrieves FDA drug shortage entries matched by generic name substring, and enumerates the returned fields. It is clearly distinct from siblings like brand_recalls, food_outbreaks, and vehicle_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?

Usage is implied by the name and the matching rule ('generic name contains the words given'), but there is no explicit when-to-use or when-not-to-use guidance and no named alternative among the sibling recall/outbreak 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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds value beyond them by disclosing ordering (newest first) and the per-entry fields (pathogen, product, case count, status, recall flag, advisory link). It omits any note on paging behaviour for the limit parameter.

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 tightly packed sentence with the ordering and returned fields front-loaded; no filler and nothing repeated from 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 carries the return-value burden and does so by enumerating the fields and the advisory link. It is nearly complete, lacking only paging semantics for limit and any note on how current the list is.

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

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

The single limit parameter has 0% schema description coverage and is never mentioned in the description, so nothing compensates. The schema's default/min/max give an agent a rough idea, but the description contributes no meaning about what the limit controls or how to page.

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 (lists) and resource (FDA foodborne outbreak investigations), plus the exact contents of each entry. The resource domain cleanly separates it from siblings like brand_recalls, vehicle_recalls, drug_shortage and tap_water without needing to name them.

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 subject matter implies when it applies — foodborne outbreak lookups as opposed to product recalls — but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as search_recalls. Usage is inferable 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 and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior the annotations cannot convey: results are capped at the newest 20 with a total count, and a specific class of recalls (nationwide-only distribution) is excluded and tallied separately. It does not mention auth or rate limits, but for a read-only query that is minor.

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 dense sentences with no filler. The result cap and agency scope come first, and the exclusions (nationwide-only, CPSC/NHTSA) follow in the same breath — nothing is padded.

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 carries the return shape (newest 20 plus a total) and the agency coverage, which is what an agent needs to interpret results. It stops short of explaining matching behavior for the state value, but the tool is simple enough that nothing critical 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% and the single parameter already documents that a state name or two-letter code is accepted (e.g. Texas or TX). The description adds no syntax or matching detail beyond that, so the baseline 3 for a fully-documented schema 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 states a specific verb and resource (recalls filtered to those whose distribution text names a state) and pins the exact data scope: FDA food/medicine/device/veterinary plus USDA FSIS. It even carves out what is not covered (CPSC, NHTSA), which cleanly separates it from vehicle_recalls without the agent needing to open 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?

It gives clear conditions for the state filter: recalls saying only 'nationwide' name no state and are counted separately, and CPSC/NHTSA do not record states at all. That tells the agent when this tool will and won't produce results, though it never names an explicit alternative (e.g. search_recalls) for the uncovered cases.

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 non-open-world behavior, and the description adds valuable context: source agencies, result ordering, date-field differences, and the special removed_from_nhtsa_file field. It does not discuss auth or rate limits, but those are not clearly required here.

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 purpose is front-loaded, and most sentences carry useful scoping or field semantics. It is dense and somewhat run-on, but not padded with irrelevant material.

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 helpfully explains the recall date fields and the NHTSA removed-field marker. It is nearly complete for calling the tool, though it omits how to choose among sibling recall tools and does not explain the limit parameter.

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 query parameter is documented in the schema and further illustrated by the description's examples such as product, brand, hazard, lot code, and UPC. The limit parameter has no schema description and is not explained in the description, leaving part of the parameter surface unaddressed.

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: finding U.S. recalls and notices across four named agencies. It also clarifies the searchable fields and geographic scope. Sibling differentiation is only implicit, since it does not explicitly say when to prefer brand_recalls, vehicle_recalls, or recalls_in_state.

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 useful scope guidance, including that Canadian, UK, and EU notices are excluded and that results are ordered by newest and best match. However, it does not explicitly state when to use this tool versus the sibling recall tools, even though vehicle and brand recall siblings exist.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior the annotations do not: a cap of 6 results, an ordering rule ('most people first'), a bounded time window (three years before the file date), and an explicit scope disclaimer that these are historical violation records, not a current water-quality test.

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 and result contents, with no filler. The first sentence is dense and the clause 'since three years before its file date' is awkward, but 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?

There is no output schema, so the description carries the return-value burden, and it does so well by enumerating systems, violations, contaminants/rules, and the source page. The only real gap is the absence of any guidance about result limits, empty ZIP matches, or sibling alternatives.

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 a single parameter at 100% schema coverage, the schema already documents the 5-digit ZIP format and example. The description's phrase 'a ZIP code's people' loosely frames the lookup but adds no syntax, format, or edge-case detail 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?

The description names a concrete resource (community water systems for a ZIP code) and specifies exactly what is returned: systems, health-based violations, contaminants/rules, and a source page. It is clearly distinct from recall-oriented siblings by domain, though it never names or contrasts 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: the required ZIP parameter and the title make the when-to-use obvious, but there is no statement of when to prefer this over the recall siblings or any precondition. The closing caveat ('records of violations, not a test of the water today') frames interpretation rather than routing.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-schema behavior: results are capped at the newest 30 with the total count disclosed, complaint coverage starts in 1995 and is broken out by part, and recalls may not apply to a specific VIN.

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 dense, front-loaded sentences that lead with the data returned and the result cap, then the applicability caveat. The VIN sentence earns its place by warning the agent not to overstate recall coverage for a user's specific car, though the phrasing is slightly indirect.

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 does part of the return-shape job: it discloses the 30-result cap, the total-on-record figure, and that complaints are counted by part. It still omits how to retrieve beyond the 30 and any field-level detail, but for a 3-parameter lookup this is largely 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 only 33% (only year is documented), so the description has to carry the load for make/model. It names all three inputs but adds no format guidance such as casing, make naming conventions, or whether aliases (e.g., 'Chevy') are accepted, leaving the gap only partially filled.

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 pair: NHTSA recalls plus owner complaint counts for a make/model/model-year, with result scope (newest 30, total on record). That is distinct from siblings like brand_recalls, recalls_in_state, or search_recalls, though the description never names those alternatives to sharpen the boundary.

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 required make/model/year framing and the caveat that a recall applies only to listed vehicles, with VIN verification pointed to nhtsa.gov/recalls. However, there is no explicit when-to-use-this-vs-brand_recalls/search_recalls guidance or stated prerequisites.

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