Medicine names, label text, safety reports, recalls, shortages and approvals from regulators
Score is being calculated.
What brand names is this drug sold under? Lists the US brand names whose products contain a generic ingredient (e.g. simvastatin: Zocor, Vytorin, Flolipid), with RxCUI codes, from the U.S. National Library of Medicine RxNorm. Useful for travellers, carers and anyone comparing US and UK medicine names. Brands are US only (UK-only brands are not listed), the list includes combination products containing the ingredient, and it does not say which brands are currently marketed. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| generic | No | string, required, the generic ingredient name (e.g. "simvastatin") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered; the description goes further by disclosing the data source (RxNorm/NLM), that it returns RxCUI codes, that combination products are included, that UK-only brands are excluded, that it does not indicate which brands are currently marketed, and that it costs 1 credit. These are exactly the caveats an agent needs before relying on results.
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?
Purpose is front-loaded in the first sentence, with scope limits and cost after it, so an agent can stop reading early if it only needs the purpose. It is dense but not padded, though the 'travellers, carers' audience sentence is the weakest link and could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter lookup with no output schema, the description covers what comes back (brand names with RxCUI codes), where it comes from, and the three limitations that would otherwise cause misevaluation (US-only, combination products included, no marketing-status signal). Nothing material 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 description coverage is 100% and there is only one parameter, so the schema already documents 'generic'. The description reinforces its meaning indirectly by showing a generic name example and noting that combination products containing the ingredient are included, but adds no format or normalization guidance (e.g. spelling tolerance, case) beyond the schema. 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 opens with a direct question that names the exact output ('What brand names is this drug sold under?') and follows with a concrete verb+resource statement plus a worked example (simvastatin: Zocor, Vytorin, Flolipid). It is clearly distinguishable from siblings like drug_generic_ingredient and drug_name_match, which go in the opposite direction or perform matching.
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 a use context ('useful for travellers, carers and anyone comparing US and UK medicine names') and states the key scoping condition that the brands are US-only. It stops short of explicitly naming an alternative tool or saying when NOT to use it, so it falls just below the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who should not take this drug? Lists the medical conditions a drug is recorded as contraindicated with (ci_with) in the US Veterans Health Administration MED-RT reference, via the U.S. National Library of Medicine RxClass (e.g. metformin: Renal Insufficiency, Liver Diseases, Acidosis), with MeSH condition IDs. Useful for students, carers and agents doing a first-pass reference check. It is a reference list, not the full warnings in a product label; drug-drug interactions are not covered, and anyone affected should check with a pharmacist or prescriber. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | string, required, a generic or brand drug name (e.g. "metformin") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld and non-destructive, and the description adds genuinely new behavioral context: the upstream authority (US VHA MED-RT via NLM RxClass), the fact that results are a reference list rather than label warnings, and a cost of 1 credit. It does not cover edge behavior such as what is returned for an unknown or ambiguous drug name.
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 scope statement and example are front-loaded and the caveats are grouped at the end, so the agent hits the essential information first. It is somewhat over-stuffed for a single-parameter lookup, with the 'students, carers and agents' audience sentence and the pharmacist/prescriber disclaimer being the weakest-value 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 one-parameter read-only lookup with no output schema, the definition supplies source provenance, a sample of returned fields (conditions plus MeSH IDs), and clear scope limits. The only meaningful gap is return-shape specifics such as what an empty or unmatched result looks like.
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 one parameter at 100% schema description coverage, the schema already documents 'name' as a generic or brand drug name with an example, so the baseline is 3. The description's 'via ... (e.g. metformin: ...)' reinforces the example but adds no new guidance on brand vs generic matching or ambiguity handling.
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 ('Lists the medical conditions a drug is recorded as contraindicated with'), names the underlying reference (MED-RT via RxClass), and gives a concrete example (metformin: Renal Insufficiency, Liver Diseases, Acidosis). The framing 'Who should not take this drug?' plus the explicit contraindication scope separates it cleanly from siblings like drug_listed_uses or drug_pharmacologic_class.
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 positive context ('useful for students, carers and agents doing a first-pass reference check') and exclusions ('not the full warnings in a product label; drug-drug interactions are not covered'), which tells an agent when this tool is the wrong choice. It stops short of naming the sibling tools that would cover warnings or interactions, so routing is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What is the generic name of this brand? Returns the active ingredient or ingredients of a US brand-name medicine (e.g. Zocor: simvastatin; Vytorin: ezetimibe and simvastatin), with RxCUI codes, from the U.S. National Library of Medicine RxNorm. Useful for patients, travellers and pharmacy staff looking for the generic equivalent. Brand names must be US ones known to RxNorm; it does not compare prices or say whether a generic is interchangeable for a given patient. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | string, required, the brand name (e.g. "Zocor") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's added value is the data provenance (U.S. National Library of Medicine RxNorm), the geographic scope limit to US brands, what the response contains (ingredients plus RxCUI codes), and the 1-credit cost. The one gap is guidance on what happens when a brand is not found in RxNorm, which for an open-world lookup is the most likely failure mode.
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, example output, provenance, and caveats are front-loaded in a compact block with no filler or repetition. The audience sentence ('useful for patients, travellers and pharmacy staff') is the weakest line, adding framing rather than actionable information, but it is short enough not to distract.
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 naming the fields (ingredient names, RxCUI codes) and the source. For a single-parameter read-only lookup this is nearly complete; only the not-found / ambiguous-brand behavior is left unstated.
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 there is only one parameter, with the schema already showing the format ('the brand name (e.g. "Zocor")'). The description reinforces this with two example brand names and the US-only constraint, but adds no additional syntax or normalization guidance beyond what the schema states. 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?
Leads with a specific question form ('What is the generic name of this brand?') and states a concrete verb+resource: returns active ingredient(s) of a US brand-name medicine, with two worked examples (Zocor: simvastatin; Vytorin: ezetimibe and simvastatin). The direction of the mapping (brand -> ingredient) implicitly distinguishes it from siblings like drug_brand_names that go the other way.
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?
States the applicable population ('patients, travellers and pharmacy staff looking for the generic equivalent') and two explicit exclusions: it does not compare prices and does not say whether a generic is interchangeable for a given patient. It also gives a hard prerequisite ('Brand names must be US ones known to RxNorm'). It stops short of naming sibling tools such as drug_spelling_suggest or drug_name_match as fallbacks when the brand is unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What conditions is this drug used for? Lists the conditions a drug is recorded as able to treat (may_treat) in the US Veterans Health Administration MED-RT reference, via the U.S. National Library of Medicine RxClass (e.g. metformin: Diabetes Mellitus, Type 2), with MeSH condition IDs. Useful for students, carers and agents wanting a short structured list rather than label prose. MED-RT is a reference terminology, not a full or current list of licensed indications, and off-label uses are not covered; not medical advice. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | string, required, a generic or brand drug name (e.g. "metformin") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it discloses the authoritative source, the semantic scope ('may_treat' only, excluding off-label), that MeSH condition IDs are included, and the cost of 1 credit. It also warns the dataset is a reference terminology rather than current licensing data, which is exactly the caveat an agent needs before presenting results.
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 user-facing question, then the answer, source, example, and caveats. The cost parenthetical and multiple disclaimers add bulk, but each clause carries real information; minor tightening would improve it.
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 fully carries the return-value burden: it explains what is returned (condition names plus MeSH IDs), what is excluded, and where the data comes from. Nothing needed to call this single-parameter read tool 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 parameter already documents generic-or-brand names with the 'metformin' example, so the description adds little beyond restating the same example. No extra guidance on brand vs generic resolution or ambiguity handling is provided, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Lists the conditions a drug is recorded as able to treat') and pins the exact source field ('may_treat') in MED-RT via RxClass. The example (metformin: Diabetes Mellitus, Type 2) makes the output immediately recognizable and separates it from siblings such as drug_contraindicated_conditions or drug_pharmacologic_class.
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?
Clearly frames intended users and the use case ('a short structured list rather than label prose') and gives explicit exclusions: not a full or current list of licensed indications, off-label uses not covered, not medical advice. It does not name a sibling tool to route to when the agent actually wants contraindications or class data, so routing guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What is the standard name and ID for this medicine? Matches a messy drug name, brand, or name-plus-strength (e.g. 'zocor 10mg', 'metformin 500') to the closest US RxNorm concepts and their RxCUI codes, best match first, from the U.S. National Library of Medicine RxNav approximate-match service. Useful as the first step for medication lists, reconciliation and any tool that needs an RxCUI. Matches are ranked by text similarity, not checked clinically; only RxNorm-source names are returned, and non-US brand names may not match. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| term | No | string, required, the drug name as written, optionally with strength or form (e.g. "zocor 10 mg") | |
| limit | No | integer, optional, 1-10 matches to return, default 5 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/openWorld/non-destructive, yet the description still adds meaningful behavior: results are ordered best-match-first, ranked purely by text similarity with no clinical validation, only RxNorm-source names are returned, and each call costs 1 credit. These are non-obvious caveats an agent could not infer from structured fields.
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 question and the matching behavior, then caveats, then cost. Dense and largely waste-free; the parenthetical credit note and repeated 'name-plus-strength' phrasing are minor redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the work of explaining returns: closest RxNorm concepts, RxCUI codes, best match first. For a simple two-parameter read tool this is nearly complete, though the exact response fields and how many candidates appear by default are left implicit.
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 already carries the term format example ("zocor 10 mg") that the description echoes. The description says nothing about the limit parameter (range, default) beyond what the schema documents, so it adds little 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?
States a concrete verb and resource (match a messy drug name/brand/strength to RxNorm concepts and RxCUI codes) and scopes the source (NLM RxNav approximate match). It is clearly separable from sibling tools like drug_spelling_suggest, drug_brand_names, or drug_generic_ingredient, which return different artifacts.
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?
"Useful as the first step for medication lists, reconciliation and any tool that needs an RxCUI" gives a clear usage context and ordering relative to downstream tools. It also states exclusions (non-US brand names may not match, text-similarity ranking rather than clinical checking) but never names a specific sibling alternative, so it stops just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What type of drug is this? Returns a drug's Established Pharmacologic Class as used in US FDA labelling (e.g. sertraline: Serotonin Reuptake Inhibitor; simvastatin: HMG-CoA Reductase Inhibitor), via the U.S. National Library of Medicine RxClass. Useful for patients, students and agents answering 'is it an SSRI / statin / opioid?'. Classes come from FDA product labels only, so older or non-US drugs may have none; it does not describe effects, safety or dosing. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | string, required, a generic or brand drug name (e.g. "sertraline") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover read-only and idempotency, and the description adds real context beyond them: the data originates from FDA product labels only, coverage gaps are possible, and each call costs 1 credit. It does not say how many classes may be returned or how multi-class drugs are presented.
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 question it answers, then examples, source, caveats and cost in a logical order. The 'useful for patients, students and agents' clause is mild filler and the paragraph is dense, but nothing is redundant enough to hurt.
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 one simple parameter, no output schema and permissive annotations, the description supplies what is missing: return content, data provenance, coverage limits and cost. The only gap is the exact response shape when a drug has several established classes.
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 schema already documents the single 'name' parameter including the generic-or-brand allowance. The description's examples restate the same input format rather than adding syntax or matching behavior (e.g. fuzzy matching, which sibling drug_name_match handles).
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 resource (Established Pharmacologic Class from FDA labelling) and gives two concrete examples (sertraline → Serotonin Reuptake Inhibitor; simvastatin → HMG-CoA Reductase Inhibitor) plus the upstream source (NLM RxClass). This clearly separates it from siblings like drug_brand_names, drug_generic_ingredient and drug_listed_uses.
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?
Frames the use case explicitly ('is it an SSRI / statin / opioid?') and states when the tool won't help ('older or non-US drugs may have none', 'does not describe effects, safety or dosing'). It does not name the specific sibling tools an agent should use for those other questions, which keeps it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How do you spell this medicine? Suggests correctly spelt drug names for a misspelt or misheard one (e.g. 'ambienn' to 'ambien'), from the U.S. National Library of Medicine RxNorm spelling service. Useful for voice and OCR input, chat agents and anyone typing a prescription name from memory. Suggestions are names in the US RxNorm vocabulary only, without strengths; they say nothing about whether a drug is right for anyone. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | string, required, the drug name as typed or heard (e.g. "ambienn") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuine value beyond that: the upstream source, the scope limit (US RxNorm vocabulary only, no strengths), the disclaimer that results say nothing about clinical appropriateness, and a cost of 1 credit. It does not describe the shape of the returned suggestions, which is the one remaining behavioural gap.
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?
Opens with the user-facing question, then delivers what it does, an example, the source, audience, scope limits and cost in tight succession. Every clause carries information — nothing is redundant with the annotations or schema beyond the necessary framing.
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 one-parameter, read-only suggestion tool with full annotation coverage and no output schema, the description covers purpose, source, scope limits and cost, which is enough to call it correctly. Only the expected form of the returned suggestions is 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?
Schema coverage is 100% and the single 'name' parameter is fully documented with the same 'as typed or heard' framing and the same 'ambienn' example used in the description. The description therefore adds essentially no parameter 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 and resource ('suggests correctly spelt drug names for a misspelt or misheard one') and anchors it with a concrete example ('ambienn' to 'ambien') plus the data source (NLM RxNorm spelling service). An agent can immediately tell this is spelling correction, not drug name lookup or interaction checking.
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 clear usage context — voice input, OCR, chat agents, typing from memory — which implies when to reach for it. It stops short of naming alternatives such as drug_name_match or drug_brand_names for cases where the spelling is already known, so routing among the many drug siblings is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds US FDA 510(k) clearances by applicant (maker) and/or device name, newest decision first: K number, device, decision, clearance type, review time and device class. Answers "is this device FDA cleared?" and "what has this competitor had cleared recently?" for MedTech founders, regulatory consultants and investors. Source: FDA 510(k) premarket notification database via openFDA. Covers 510(k) only; high-risk Class III devices go through PMA (see fda_device_pma_approvals) and De Novo grants are not included. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | integer, optional, 1-50, number of clearances to return, default 10 | |
| device | No | string, optional (applicant or device required), device name as submitted, e.g. "glucose monitor" | |
| applicant | No | string, optional (applicant or device required), company that submitted the 510(k), e.g. "Dexcom" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: result ordering (newest first), the source database (openFDA 510(k) premarket notifications), the scope boundary, and a 1-credit cost. It stops short of saying whether applicant/device matching is exact or fuzzy and how results are capped, which is the remaining behavioral gap.
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 purpose and result shape, then scope exclusions, then source and cost — a sound ordering with no wasted clauses. The audience list ("MedTech founders, regulatory consultants and investors") is mild filler that a routing agent does not strictly need.
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, and the description compensates by enumerating the returned fields (K number, device, decision, clearance type, review time, device class) and the sort order. Combined with the coverage boundaries and cost note, an agent has everything needed to call it correctly and interpret the response.
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%, including the 'applicant or device required' constraint and example values, so the baseline is 3. The description echoes the 'and/or' combining logic of applicant and device but adds no detail on match semantics (substring vs exact) or how the string-typed limit is parsed, so it does not exceed the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Finds US FDA 510(k) clearances"), the two filter dimensions, the sort order (newest decision first), and the exact fields returned. A reader can distinguish it from fda_device_pma_approvals and fda_device_classification 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?
Explicitly frames the two questions it answers ("is this device FDA cleared?" and "what has this competitor had cleared recently?") and names the exclusion: Class III goes to PMA with a pointer to fda_device_pma_approvals, and De Novo grants are not covered. That is a clear when-to-use / when-not-to-use / alternative triple.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the FDA classification for a type of medical device: risk class (I, II or III), three-letter product code, regulation number, medical specialty, definition, the usual premarket route (510(k), PMA or exempt), and whether it is an implant or life-sustaining. Answers "what class is my device?" and "do I need a 510(k)?" for start-ups, importers and consultants. Source: FDA product classification database via openFDA. US classification only; it does not cover UK/EU (UKCA/CE) classes, and exemptions can carry limitations set out in the regulation. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | string, optional (device or code required), three-letter FDA product code, e.g. "OLK" | |
| limit | No | integer, optional, 1-20, number of device types to return, default 10 | |
| device | No | string, optional (device or code required), generic device type, e.g. "pulse oximeter" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description correctly spends its space elsewhere: data provenance (openFDA product classification database), the US-only coverage boundary, the caveat that exemptions can carry regulatory limitations, and the 1-credit cost. That is meaningful context an agent cannot get from the annotations, though it does not discuss result volume or what an empty result means.
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 return payload is front-loaded, then scope limits, then caveats and cost — a sensible order with no filler sentences. Slightly padded by the audience enumeration ("start-ups, importers and consultants"), which adds framing but little operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by listing every returned field, so the agent knows what it will receive before calling. Combined with source, jurisdiction limit, caveat and cost, nothing material is missing for a read-only lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter already states its format, the code-vs-device requirement, and the 1-20 limit range. The description adds no further guidance on parameter choice (e.g. preferring a code for precision over a free-text device name), so it sits at the baseline where the schema does 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?
Opens with a specific verb+resource ("Returns the FDA classification for a type of medical device") and enumerates exactly what comes back: risk class, product code, regulation number, specialty, definition, premarket route, implant/life-sustaining flags. It is clearly distinguishable from siblings like fda_device_510k_clearances or fda_device_pma_approvals, which cover the downstream clearance records rather than the classification itself.
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 concrete use cases ("what class is my device?", "do I need a 510(k)?") tied to named audiences, which tells the agent the triggering intent. It also supplies a when-not constraint via jurisdiction ("US classification only; it does not cover UK/EU (UKCA/CE) classes"). It never explicitly names the sibling tools to use for clearance/approval histories, which keeps it short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds US FDA premarket approval (PMA) decisions for high-risk Class III devices, including supplements, by applicant and/or trade name, newest first: PMA and supplement numbers, decision, supplement type and reason, and FDA's approval statement. For regulatory affairs teams and investors tracking approvals and changes for implants, heart valves, pacemaker leads and similar devices. Source: FDA PMA database via openFDA. Complements fda_device_510k_clearances; most results for large makers are supplements (manufacturing or labelling changes), not new devices. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | integer, optional, 1-50, number of decisions to return, default 10 | |
| device | No | string, optional (applicant or device required), trade name, e.g. "Symplicity" | |
| applicant | No | string, optional (applicant or device required), company holding the PMA, e.g. "Medtronic" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, open-world and non-destructive semantics, so the bar is lower. The description adds real value beyond them: results are ordered newest first, a source is named (openFDA PMA database), and it warns that most results for large makers are manufacturing/labelling supplements rather than new devices — a behavioral caveat that prevents misinterpretation. It omits only pagination/result-cap behavior, which the schema's limit parameter 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?
Front-loaded with purpose, then fields returned, audience, source, sibling relationship, and the supplement caveat — every clause carries information. The audience sentence ('For regulatory affairs teams and investors…') and the trailing '(cost: 1 credit)' are the least load-bearing parts but still orient the agent.
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 itself — and it does, enumerating PMA/supplement numbers, decision, supplement type and reason, and FDA's approval statement. Combined with the ordering note and source attribution, an agent has everything needed to call and interpret the result.
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 three parameters are documented in structured fields; baseline 3 applies. The description's 'by applicant and/or trade name' does clarify that the two filters can be combined rather than being mutually exclusive, which is a small addition beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Finds US FDA premarket approval (PMA) decisions for high-risk Class III devices, including supplements,' and names the distinguishing sibling 'fda_device_510k_clearances'. An agent can immediately tell this apart from the 510(k) clearance tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear selection context (high-risk Class III devices, implants, heart valves, pacemaker leads) and explicitly frames itself as complementary to fda_device_510k_clearances. It does not state an explicit when-not rule (e.g., use 510k for moderate-risk Class II), but the risk-class framing makes the split inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Counts reports in the FDA MAUDE database for a device (generic type or brand name) by reported outcome: malfunction, injury, death or other. Gives journalists, litigation researchers and patients a quick sense of the reporting record for a device type, with the essential caveat attached. Source: FDA MAUDE medical device reports via openFDA. Counts are of reports, not confirmed incidents or causes, and cannot be used to rank how safe devices are; it does not return individual report narratives. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| device | No | string, required, device generic name or brand name, e.g. "insulin pump" or "Omnipod" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description correctly spends its words elsewhere: it discloses the data source, that results are report counts rather than confirmed incidents, that no narratives are returned, and that each call costs 1 credit. That is real behavioral context beyond the structured fields, though it says nothing about result shape or limits per outcome bucket.
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 breakdown before the audience and caveats, and every sentence carries substance. The caveat material is slightly repetitive in spirit (reports-not-incidents is restated across the outcome note and the caveat sentence), but it is defensible for a tool whose output is easily misread.
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 one-parameter, no-output-schema tool this is close to sufficient — it tells an agent what categories come back and that no narratives are included, compensating for the absent output schema. The remaining gap is scope of matching (does a brand name like "Omnipod" aggregate across models?), which matters for interpreting the counts.
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 itself with examples ("insulin pump", "Omnipod"). The description's parenthetical "generic type or brand name" essentially restates the schema, adding no syntax, normalization, or matching-behavior guidance. Baseline 3 applies when the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (counts) and resource (reports in FDA MAUDE) scoped by device and broken down by reported outcome category. It also carves out a negative boundary (no individual report narratives), which keeps it distinct from narrative-level siblings. It stops short of naming which sibling to pick instead of fda_device_recalls or fda_device_510k_clearances, so it isn't fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Gives journalists, litigation researchers and patients a quick sense of the reporting record" supplies explicit use context, and "cannot be used to rank how safe devices are" states a when-not-to-use constraint. What's missing is routing language: no alternative tool is named for callers who actually want recall records, clearance history, or individual reports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists US FDA medical device recalls matching a product or firm name (for example "insulin pump", "CPAP", "Philips"), newest posted first, with the reason, root cause, what users were told to do, quantity and distribution. Useful for patients, clinicians and procurement teams checking whether a device type or maker has had recalls in the United States. Source: FDA device recall database via openFDA. US recalls only (not UK MHRA field safety notices); it does not confirm whether a specific serial number is affected, and this endpoint does not carry the Class I/II/III recall severity. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | integer, optional, 1-50, number of recalls to return, default 10 | |
| query | No | string, required, device description or recalling firm name, e.g. "insulin pump" or "Medtronic" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent safety, and the description adds substantial behavior beyond them: result ordering, the exact payload fields (reason, root cause, user actions, quantity, distribution), the upstream source (openFDA device recall database), geographic scope, and two explicit data gaps. The 1-credit cost note is also operationally useful.
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 purpose and ordering, then use case, source, caveats, and cost in a logical progression. It is information-dense with little waste, though the final limitations sentence is a long run-on that could be split for faster scanning.
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 returned fields and ordering, and it closes the main risk areas (geography, severity absence, serial-number granularity) for a recall-lookup tool. An agent has everything needed to decide and call 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% and both parameters are documented there, including the same "insulin pump" / "Medtronic" examples. The description reinforces that the query matches product description or firm name but adds no syntax, matching-tolerance, or limit guidance 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 and resource (lists US FDA medical device recalls) plus the matching dimension (product or firm name) and ordering (newest posted first). The examples "insulin pump", "CPAP", "Philips" make the query semantics concrete and distinguish it from general product or vehicle recall tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly frames the use case (patients, clinicians, procurement checking whether a device type or maker has had US recalls) and states clear exclusions: US only, not UK MHRA field safety notices, does not confirm serial-number-level impact, and no Class I/II/III severity. It stops short of naming sibling tools such as recall_campaign_details or fda_device_problem_reports for those uncovered needs, so it is strong but not fully routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Is there a shortage of this medicine in the US? Lists entries on the FDA drug shortage list for a generic name, most recently updated first: each presentation's availability, status (current, resolved or to be discontinued), company, reason, estimated recovery note and posting dates. For pharmacists, procurement teams and patients. Source: U.S. FDA openFDA drug shortages. US supply only, not UK or NHS stock; the FDA list does not show local pharmacy stock. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | string, required, US generic name, e.g. methylphenidate, carboplatin, amoxicillin | |
| limit | No | integer, optional, maximum entries to list, 1-20, default 10 | |
| status | No | string, optional, current, resolved or discontinued (to be discontinued), default all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely useful context beyond that: result ordering, the per-entry fields returned, the openFDA source, the US-only scope limit, and a stated cost of 1 credit.
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 user-facing question is front-loaded, followed by what is returned, audience, source, and scope caveats in a tight sequence. It is dense but each clause carries information; the credit-cost note is the only element that could be trimmed.
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 returned entry fields and ordering, and it flags the scope boundary an agent could otherwise get wrong. It does not mention how the limit parameter interacts with result volume or what an empty result means, which are minor residual gaps for a simple three-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the three parameters are already documented, and the description largely restates them (generic name, current/resolved/discontinued status). It adds mild meaning by implying the name should be a generic rather than brand name and by noting the recency ordering, but no format or edge-case detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description leads with a concrete question then states the specific action: list FDA drug shortage entries for a generic name, sorted most-recently-updated first. It is unambiguously distinguishable from siblings like fda_drug_side_effects_reported and fda_ndc_lookup because it names the exact dataset and the returned fields.
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 when-to-use framing ('Is there a shortage of this medicine in the US?') and explicit exclusions: US supply only, not UK/NHS stock, and not local pharmacy stock. It does not name a sibling alternative for the adjacent need (e.g. identifying a drug or checking side effects), 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.
What side effects do people report for this medicine? Ranks the reactions most often named in reports to the FDA Adverse Event Reporting System (FAERS) for a medicine, with report counts. Popular with patients, journalists and pharmacovigilance work. Source: U.S. FDA openFDA FAERS. Reports are unverified, include every drug the patient was taking, and do not show the medicine caused the reaction or how common it is; label side effect rates are a different measure. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | string, required, brand or generic name, e.g. metformin | |
| limit | No | integer, optional, number of reactions to rank, 1-50, default 10 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, open-world and non-destructive behavior, and the description adds substantial context beyond that: provenance (openFDA FAERS), that reports are unverified and polypharmacy-contaminated, that they do not establish causation or population frequency, and the 1-credit cost. That is exactly the behavioral caveat an agent needs before quoting results.
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 opens with the user-facing question, then the mechanism, then caveats, then cost — well front-loaded with no dead sentences. The caveat sentence is long and dense, but every clause (unverified, all drugs included, no causation, distinct from label rates) carries real 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 two-parameter read-only lookup with no output schema, the definition covers purpose, provenance, limitations, and cost. Nothing an agent needs to call it correctly or interpret its output responsibly 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 description coverage is 100%, so both parameters (name, limit) are already documented with examples and ranges. The description implies the medicine input ('for this medicine') and report counts but adds no syntax, format, or naming detail beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it RANKS the reactions most often named in FAERS reports, with report counts. This is clearly distinguishable from siblings like fda_drug_shortages (shortages) and fda_ndc_lookup (product codes), so an agent can route without opening 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 context for use ('popular with patients, journalists and pharmacovigilance work') and, importantly, scopes what the data is not. It stops short of naming an explicit alternative (e.g. clinical_trials or label data) for when the agent actually needs causal or prevalence rates, so it is clear but lacks explicit alternatives/exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What is this NDC code, or what products exist for this medicine name? Looks up US medicine products in the FDA National Drug Code Directory by brand or generic name or by NDC (product 0573-0169, package 0573-0169-02, or the 11-digit billing form 00573-0169-02 / 00573016902): labeller, active ingredients and strengths, dosage form, route, OTC or prescription, approval reference and pack sizes. For pharmacy, billing and supply-chain work. Source: U.S. FDA openFDA NDC Directory. US-listed products only; name searches return finished medicines (not bulk ingredients), and delisted products are missing. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| ndc | No | string, NDC: product with hyphens (0573-0169), package with hyphens (0573-0169-02), or a 10- or 11-digit package code with or without hyphens (00573-0169-02, 00573016902); give this or name | |
| name | No | string, brand or generic name (e.g. Advil); give this or ndc | |
| limit | No | integer, optional, maximum products for a name search, 1-20, default 5 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, idempotent=true, openWorld=true, so safety is covered; the description adds real value on top with data-coverage caveats (US-only, no bulk ingredients, missing delisted products) and a cost of 1 credit. It does not discuss result ordering or behavior when an NDC matches nothing, which keeps it off a 5.
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 front-loaded with a framing question and the core lookup statement, followed by format examples, returned fields, audience, source, and caveats. Dense rather than bloated, though the parenthetical format examples are largely redundant with the schema and could be trimmed.
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 reference lookup with no output schema, the description explicitly enumerates what comes back (labeller, active ingredients and strengths, dosage form, route, OTC vs prescription, approval reference, pack sizes) plus source and coverage limits. An agent has everything needed to decide to call it and to interpret the response.
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 three parameters are already documented in the schema. The description restates the NDC formats (product, package, 11-digit billing form) and the name-or-NDC choice, which duplicates rather than extends the schema; the 'limit' behavior is left entirely to the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource combo: 'Looks up US medicine products in the FDA National Drug Code Directory by brand or generic name or by NDC.' It names both lookup keys and the fields returned, which clearly separates it from siblings like fda_drug_shortages and fda_drug_side_effects_reported even before 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?
It gives a concrete usage context ('pharmacy, billing and supply-chain work') and, more usefully, explicit exclusions: US-listed products only, name searches exclude bulk ingredients, and delisted products are absent. It stops short of naming a sibling alternative when a user really wants shortages or adverse events, so it is strong but not a full when/when-not/alternative map.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Counts the reactions most often reported to the FDA for a veterinary medicine active ingredient, optionally in one species, for example carprofen in dogs, most frequent first. Answers pet owners' and vets' questions about what has been reported with flea, worming, pain and allergy medicines. Source: FDA Center for Veterinary Medicine adverse event reports via openFDA. Counts are reports, not confirmed side effects or rates; search by active ingredient (e.g. "Oclacitinib" rather than a brand name), and it covers US reports only. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | integer, optional, 1-50, number of reactions to return, default 20 | |
| species | No | string, optional, animal species as reported, e.g. "Dog", "Cat", "Horse"; default all species | |
| ingredient | No | string, required, active ingredient, e.g. "Carprofen", "Fluralaner", "Oclacitinib" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely non-obvious context: the data source is FDA CVM adverse event reports via openFDA, coverage is US-only, and counts are reports rather than confirmed side effects or rates. It also discloses a 1-credit cost. The only gap is that it does not sketch the response shape for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose and example are front-loaded, and each subsequent sentence carries a distinct constraint (source, interpretation caveat, input rule, geography, cost). It is on the dense side but nothing is pure padding; the parenthetical credit note could be trimmed.
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 three-parameter read-only aggregation with no output schema, this covers purpose, source, scope, input conventions and interpretation limits. The main remaining unknown is what the returned records look like (reaction label plus count fields), which the description only implies.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage the baseline is 3, but the description adds real meaning: it clarifies that the ingredient must be an active ingredient rather than a brand name, that species filtering is optional (single species only), and that results are ordered most-frequent-first. That goes beyond the schema's field-level descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (counts), a specific resource (reactions reported to FDA for a veterinary medicine active ingredient), and the aggregation/ordering behavior (most frequent first) with a concrete example (carprofen in dogs). It is clearly not the human-drug or supplement reaction tools, so an agent can select it 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?
Gives the audience and question types it answers (pet owners and vets asking about flea, worming, pain and allergy medicines) and an explicit input rule: search by active ingredient, not brand name. It stops short of naming alternatives (e.g. the human-drug side effect tool or a brand-to-ingredient resolver) as a route when the user supplies a brand name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Counts the reactions most often named in reports to the FDA (CAERS) about a food, drink, dietary supplement or cosmetic brand, for example "CELSIUS", most frequent first. Helps people asking about energy drinks, supplements and protein powders see what has been reported, with the caveat that reports are unverified. Source: FDA CFSAN Adverse Event Reporting System via openFDA. Counts are of reports mentioning each reaction, not proven side effects or rates, and small brands may have few or no reports. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | string, required, brand or product name as reported, e.g. "CELSIUS" | |
| limit | No | integer, optional, 1-50, number of reactions to return, default 20 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, open-world and non-destructive, so the description's job is to add context — and it does: counts are of reports mentioning each reaction, not proven side effects or rates, reports are unverified, small brands may return little or nothing, and the call costs 1 credit. It does not describe result ordering failures or empty-result behavior beyond the small-brand warning.
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 what is counted and for what input, then layers the necessary caveats and the credit cost. A few clauses ("Helps people asking about…", the source attribution) could be trimmed, but nothing is genuinely 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 description carries the burden of describing results and does so — reaction names paired with report counts, sorted descending, subject to the limit. Combined with the unverified-report and small-brand caveats, an agent has everything needed to call it and interpret the response.
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 both parameters (brand, limit) are already documented in structured form. The description restates the example brand "CELSIUS" and the most-frequent-first ordering but adds nothing about the limit range or brand string matching (exact vs fuzzy), so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: counts the reactions most often named in FDA CAERS reports for a named food, drink, supplement or cosmetic brand, returned most-frequent-first. The scope wording (food/drink/supplement/cosmetic brand) implicitly separates it from drug- and pet-oriented siblings such as fda_drug_side_effects_reported and fda_pet_drug_reactions.
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 concrete use cases (questions about energy drinks, supplements, protein powders) with the sharp caveat that reports are unverified and small brands may have few results. It never names an alternative tool or states when a different reaction/side-effect tool would be the better choice, so routing to siblings is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Is this NDC still active? Checks a US National Drug Code against RxNorm and reports whether it is active, obsolete, alien or unknown, which product (RxCUI and name) it maps to, the source vocabularies that list it, and its month-by-month mapping history, from the U.S. National Library of Medicine RxNav. Useful for pharmacy, billing and claims work on old or unfamiliar codes. It covers US NDCs only and reflects RxNorm's records, which can lag FDA listing changes; it does not give price, packaging or supply. (cost: 1 credit)
| Name | Required | Description | Default |
|---|---|---|---|
| ndc | No | string, required, an 11-digit NDC (e.g. "00071015523") or a hyphenated 10-digit NDC (4-4-2, 5-3-2 or 5-4-1) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive and open-world behavior, so the description correctly focuses on things annotations cannot express: the US-only scope, the RxNorm upstream source, its known lag versus FDA listing changes, and the 1-credit cost. That is exactly the supplemental behavioral context an agent needs.
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 question opener front-loads the core purpose and each following sentence adds distinct information (outputs, audience, scope limits, cost). The middle sentence is a long run-on list of returned fields, which slightly hurts scanability but contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing returns and does so thoroughly (status categories, RxCUI and name, vocabularies, monthly history). Scope limits, data-source caveats and credit cost round out everything needed 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% and the single parameter already documents both the 11-digit and hyphenated 10-digit formats with an example. The description adds nothing about input format or validation, so it sits at the baseline where 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?
The description opens with a specific question and then states the exact operation: checks a US NDC against RxNorm and reports status (active/obsolete/alien/unknown), RxCUI mapping, source vocabularies, and monthly mapping history. This is far more than a restatement of the name, and the mention of RxNorm records lagging FDA listing changes implicitly separates it from the FDA-based sibling fda_ndc_lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete use-context (pharmacy, billing and claims work on old or unfamiliar codes) and clear exclusions (no price, packaging or supply). It stops short of naming an alternative tool for those excluded needs, so the agent is told when not to use it but not where to go instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
drug_brand_namesdrug_contraindicated_conditionsdrug_generic_ingredientdrug_listed_usesdrug_name_matchdrug_pharmacologic_classdrug_spelling_suggestfda_device_510k_clearancesfda_device_classificationfda_device_pma_approvalsfda_device_problem_reportsfda_device_recallsfda_drug_shortagesfda_drug_side_effects_reportedfda_ndc_lookupfda_pet_drug_reactionsfda_supplement_reactionsndc_statusFDA drug approvals, 510(k) device clearances, recalls and adverse-event reports.
Official FDA recalls, drug labels, adverse events and clinical trials, with cited sources.
MHRA drug and device safety alerts, recalls and Drug Safety Update bulletins, sourced from the…
French medicines (ANSM + BDPM): boxes and prices, prescription conditions, safety info, shortages.
Add one secure layer between your agents and this server.