NIH supplement checks: upper limits, drug and herb interactions, FDA recalls, with citations.
Scored across 7 tools
The three product-retrieval tools (products_search, products_lookup, products_get) overlap in purpose but are cleanly differentiated by input type (name/brand, barcode, DSLD ID). The interactions_check vs stack_analyze boundary is explicitly addressed in descriptions, though stack_analyze also performs interaction checks, creating mild redundancy.
Most tools follow a resource_action pattern (interactions_check, products_get, products_lookup, products_search, stack_analyze), which is predictable. Two deviations (nutrients_reference, products_fda_reports) use noun-only or noun_noun forms rather than a verb, a minor inconsistency.
Seven tools is well-scoped for a supplement analysis domain, with each tool covering a distinct capability (reference values, interactions, label retrieval, FDA reports, stack analysis). Nothing appears redundant or padded.
The surface covers the full lifecycle: discover products (search/lookup), retrieve labels (get), check safety (FDA reports, interactions), and analyze a full stack with reference values. Minor gaps exist (e.g., no explicit bulk/compare operation), but core workflows are covered without dead ends.
Which vitamins and minerals interact with given medications (generic or brand names, e.g. "warfarin", "Synthroid") or conditions, per the NIH Office of Dietary Supplements fact sheets, with timing advice (e.g. take levothyroxine 4 hours apart from calcium). No product list needed; to check an actual stack, pass medications to stack_analyze instead. Not exhaustive.
| Name | Required | Description | Default |
|---|---|---|---|
| nutrients | No | Optional: only report interactions involving these nutrients or botanicals (IDs or names, e.g. "vitamin-k", "magnesium", "St. John's wort") | |
| conditions | No | Conditions that change how NIH reads a dose: smoker (current or former, or asbestos exposure: beta-carotene), kidney_disease (potassium, magnesium, phosphorus), hemochromatosis (iron, vitamin C), lab_test_soon (biotin interferes with lab tests), cancer_treatment (antioxidant doses) | |
| medications | No | Medications the person takes, as generic or brand names ("warfarin", "Synthroid", "metformin 500 mg"). Checked against the medication interactions listed in the NIH ODS fact sheets; not exhaustive. Never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, but the description adds real value beyond them: the authoritative source (NIH ODS fact sheets), the coverage limit ("Not exhaustive"), the privacy guarantee ("Never logged"), and that timing advice is part of the result. It does not describe result shape or how conditions alter recommendations in any depth, keeping it short of 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?
Three tight sentences, front-loaded with what the tool does, followed by the alternative-tool routing and the scope caveat. Every clause carries information; nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description helpfully signals that timing advice is returned and that coverage is not exhaustive. It is nearly complete, though it never clarifies behavior when all three optional parameters are omitted, a real gap given zero required parameters.
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 documents all three parameters in detail, including enum meanings for conditions. The description's examples ("warfarin", "Synthroid", levothyroxine/calcium timing) largely duplicate what the schema shows, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: which nutrients interact with given medications or conditions, sourced from NIH ODS fact sheets, including timing advice. It explicitly distinguishes itself from the sibling stack_analyze ("to check an actual stack, pass medications to stack_analyze instead"), so an agent can route without opening either 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 an explicit when-to-use condition (checking interactions for medications/conditions, no product list needed) and names the alternative tool plus the condition that selects it (an actual product stack goes to stack_analyze). It also sets expectations with "Not exhaustive."
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
NIH reference values (RDA, EAR, AI, UL) for one vitamin or mineral at a given age and sex, with what the UL protects against. Offline and instant.
| Name | Required | Description | Default |
|---|---|---|---|
| age | Yes | Age in years. For infants use a fraction: 0.25 = 3 months; 0-5 and 6-11 month values apply under 1. | |
| sex | Yes | ||
| nutrient | Yes | Nutrient ID ("vitamin-d") or any synonym ("cholecalciferol") | |
| life_stage | No | Pregnancy or lactation (breastfeeding) reference values; requires sex "female" and age 14-50 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds the useful operational traits 'offline' and 'instant'. It does not disclose failure behavior (unknown nutrient synonyms, out-of-range ages, missing life-stage combos) or output units. There is also mild tension between 'offline' and openWorldHint=true, though 'offline' plausibly describes execution mode rather than data scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler, front-loading what is returned before the operational note. Every clause carries 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?
With no output schema, the description correctly enumerates the return payload (RDA, EAR, AI, UL plus UL-protection rationale), which is the key gap-filler. It is nearly complete for a simple reference lookup; only error/edge-case behavior and output units are unaddressed.
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 75%, close to the high-coverage baseline where the schema does the heavy lifting. The description adds that the nutrient is 'one vitamin or mineral' and that values are keyed to age and sex, but it says nothing about the optional life_stage parameter or the age-fraction convention, so it only marginally extends 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+resource: retrieves NIH reference values (RDA, EAR, AI, UL) for a single vitamin or mineral keyed by age and sex. It even names the returned data fields and the UL-protection context, so an agent knows exactly what this returns. No sibling tool overlaps with reference-value lookup, so differentiation is automatic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: 'Offline and instant' hints this is the preferred local lookup over network calls, and the nutrient/age/sex framing implies the use case. But there is no explicit when-to-use, when-not, or named alternative, and no guidance on how to handle an unknown nutrient or an age/sex combination that has no value.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FDA recalls and adverse event reports (CAERS) for one supplement, from openFDA. Give a product name, barcode, DSLD ID, or brand and name. Recalls are listed only when they carry the barcode or the brand and every product-name word; adverse event reports are counted with their most common reactions. Reports do not show that a product caused an event.
| Name | Required | Description | Default |
|---|---|---|---|
| upc | No | UPC-A or EAN barcode digits as printed on the bottle, e.g. "031604026974" (spaces and dashes are ignored) | |
| name | No | Product name as printed, used with "brand" when the product is not in DSLD | |
| brand | No | Brand (with "name", or to narrow "query") | |
| query | No | Product as the user named it; resolved to a DSLD label | |
| dsld_id | No | DSLD label ID, e.g. from /v1/products/search |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnlyHint and openWorldHint; the description adds real behavioral content beyond them: the strict recall-matching rule (barcode, or brand plus every product-name word) and the interpretive caveat that reports do not show the product caused the event. It stops short of disclosing result counts, pagination, 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?
Four sentences, front-loaded with what the tool returns and how to address a product, then the matching caveats. No filler, though the causal disclaimer could be folded more tightly into the return-description sentence.
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-shape burden and does describe the two result categories (listed recalls, counted adverse events with common reactions). For a 5-parameter, all-optional tool it is nearly complete, missing only edge behavior such as zero-match handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description genuinely adds semantics: it explains how upc, brand/name, and DSLD identifiers feed the recall-matching logic, not just listing them. The synergy between 'brand' + 'name' and the recall inclusion rule is spelled out rather than left to 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 (retrieve) and resource (FDA recalls and CAERS adverse event reports) for one supplement, sourced from openFDA. This resource is categorically distinct from every sibling (products_get, products_search, products_lookup, interactions_check, stack_analyze), so an agent can route to it without opening another 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 concrete input guidance ('Give a product name, barcode, DSLD ID, or brand and name') and explains the matching constraint that governs result inclusion, which implies how to drive the tool. However, it never states when to prefer this over siblings like products_lookup or products_get, nor any when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full normalized supplement labels by DSLD ID (up to 10): every ingredient with label amount, converted amount, form and %DV.
| Name | Required | Description | Default |
|---|---|---|---|
| dsld_id | No | DSLD label ID, e.g. from /v1/products/search | |
| dsld_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Read-only and open-world behavior is already declared by annotations, so the description's marginal contribution is the return-shape detail (ingredient-level amounts, converted amounts, form, %DV) and the 10-item cap. It says nothing about error handling for invalid IDs, permission requirements, or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with the resource, the selector, and the payload contents front-loaded, and no filler. The colon-separated field list is efficient, though the phrasing is slightly compressed at the cost of readability.
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 carry the burden of explaining returns and it does list the key per-ingredient fields, which is the most important gap filled. However, it omits the singular-vs-array parameter behavior and any error or batching semantics, leaving the definition only adequately complete for a two-parameter lookup.
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 description confirms the ID-based lookup and restates the batch limit of 10, but does not explain the relationship between the singular dsld_id and the array dsld_ids, nor which to prefer or what happens if both are supplied. With schema coverage at only 50%, this leaves real ambiguity that the description could have resolved.
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 resource ('full normalized supplement labels') and the key selector ('by DSLD ID'), and describes the payload's granularity ('every ingredient with label amount, converted amount, form and %DV'). It does not distinguish itself from siblings like products_lookup or products_search, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, and no named alternative (e.g. products_lookup vs products_search). The only usage hint is the '(up to 10)' batch ceiling, which is a constraint rather than guidance on when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a supplement by the UPC/EAN barcode printed on the bottle. Returns the newest matching DSLD label, normalized, and any older versions.
| Name | Required | Description | Default |
|---|---|---|---|
| upc | Yes | UPC-A or EAN barcode digits as printed on the bottle, e.g. "031604026974" (spaces and dashes are ignored) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower, and the description adds meaningful context: the newest matching DSLD label is returned normalized alongside older versions. It does not state what happens when no label matches or how multiple products are disambiguated, leaving a small 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?
Two tight sentences, zero filler, with the identifying action and identifier front-loaded ahead of the return-value note.
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 discloses the return shape (newest normalized DSLD label plus older versions), which is exactly the missing structured information. Only the no-match/empty-result case is left unexplained for an otherwise simple single-parameter lookup.
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 the UPC-A/EAN format, length, and space/dash handling. The description only reinforces that the code is printed on the bottle, adding marginal value 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?
States a specific verb ('Look up') and resource ('supplement by UPC/EAN barcode'), and implicitly distinguishes itself from products_search and products_get by naming the exact identifier used. An agent can tell this is the barcode-keyed retrieval tool without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'barcode printed on the bottle' implies the trigger condition for using this over products_search, but no alternative is named and there is no explicit when-not guidance. Usage is inferable, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the NIH Dietary Supplement Label Database by product name, brand or ingredient. Returns up to 10 products (one per product; older label versions listed in other_versions) with DSLD IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | ||
| limit | No | ||
| query | No | Free-text search, e.g. "vitamin d3 5000" | |
| ingredient | No | Ingredient name, e.g. "cholecalciferol" | |
| on_market_only | No | ||
| dedupe_versions | No | Collapse label versions of the same product (same brand and name) into one result, newest first; older IDs are listed in other_versions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only safety and open-world scope, so the bar is lower; the description still adds real value by disclosing that results are capped (up to 10), one row per product, and that older label versions are surfaced in other_versions. It does not address rate limits or empty-result behavior, keeping it out of the top band.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, zero filler, with the search capability front-loaded and the return contract in the second sentence. Every clause carries 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 six-parameter search tool with no output schema, the description covers the search surface and result shape but omits the default narrowing behavior (on_market_only=true), what an empty result set looks like, and any pagination guidance. Adequate but with visible gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, and the description names three of the six parameters (name/brand/ingredient) plus loosely hints at the limit cap ('up to 10'). It never explains on_market_only (default true), which silently narrows results, so it only partly compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Search) plus the resource (NIH Dietary Supplement Label Database) and the three supported search fields (product name, brand, ingredient). It also states the result shape. It stops short of naming which sibling to prefer (e.g. products_get, products_lookup), so an agent must infer 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 only implied: the searchable fields hint at when this is the right entry point versus products_get/products_lookup, but there is no explicit when-to-use statement, no exclusions, and no mention of what to do when zero results come back.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a list of dietary supplements for a person: per-nutrient daily totals against NIH upper limits (UL) and RDA/AI, which products overlap, what each UL protects against, and single-product changes that would bring an above-UL nutrient back under it. Products can be given as names ("Centrum Silver Women 50+"), barcodes, DSLD IDs, or custom ingredient lists; optional candidates are evaluated as additions. Pass the person's medications and conditions (smoker, kidney_disease, hemochromatosis, lab_test_soon, cancer_treatment) to check them against the interactions in the NIH fact sheets. Returns agent_summary (plain sentences to relay), resolutions, suggestions, interactions, nutrient_totals and data_gaps. Label data only; food is included only with diet "typical".
| Name | Required | Description | Default |
|---|---|---|---|
| age | No | Age in years. For infants use a fraction: 0.25 = 3 months; 0-5 and 6-11 month values apply under 1. | |
| sex | No | ||
| diet | No | "typical" adds the US average intake from food and drinks for this age and sex (NHANES) to estimate total intake; see with_typical_diet | none |
| lang | No | "es" writes agent_summary in Spanish (the English text is kept in agent_summary_en); other fields stay in English | en |
| foods | No | Optional, up to 30: what the person eats in a day, e.g. [{"query":"spinach cooked","amount":1,"unit":"cup"},{"query":"whole milk","grams":488}]. Added to the supplement totals in nutrient_totals[].with_foods (USDA SR28, offline). Use instead of diet "typical". | |
| detail | No | "summary" returns only what an agent needs to answer (agent_summary, flagged nutrients, suggestions, resolutions, candidate verdicts), about 1-3 KB instead of 20-40 KB | full |
| products | Yes | 1-15 products. Each is one of: {"dsld_id"}, {"query"} (a product name, resolved server-side), {"upc"} (barcode), or a custom product {"name","ingredients"}. Add "servings_per_day" to any of them. | |
| candidates | No | Optional, up to 5: products the user is considering adding. Each is evaluated as an addition to the stack in candidate_results[]; they are not included in nutrient_totals. | |
| conditions | No | Conditions that change how NIH reads a dose: smoker (current or former, or asbestos exposure: beta-carotene), kidney_disease (potassium, magnesium, phosphorus), hemochromatosis (iron, vitamin C), lab_test_soon (biotin interferes with lab tests), cancer_treatment (antioxidant doses) | |
| life_stage | No | Pregnancy or lactation (breastfeeding) reference values; requires sex "female" and age 14-50 | |
| medications | No | Medications the person takes, as generic or brand names ("warfarin", "Synthroid", "metformin 500 mg"). Checked against the medication interactions listed in the NIH ODS fact sheets; not exhaustive. Never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds genuine context on data provenance and behavior ('label data only; food is included only with diet typical') and enumerates the returned fields. It does not cover latency, resolution failure behavior, or the non-exhaustiveness of interaction checking (that caveat only appears in the schema), keeping it out of 5 territory.
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 capability is front-loaded in the first sentence, and the enumerated outputs and return fields are each load-bearing given there is no output schema. It is dense rather than padded, though the return-field list reads somewhat as an inventory and the total length is near the upper bound for a single tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 11-parameter tool with no output schema, the description compensates well by naming agent_summary, resolutions, suggestions, interactions, nutrient_totals and data_gaps, plus the summary-vs-full size trade-off. Edge-case behavior (unresolved products, empty results) and interaction-checking limits remain undocumented here, so it is strong but not exhaustive.
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 91%, so the baseline would be 3, and the description clears that bar by adding meaning the schema does not: candidate products are evaluated as additions and excluded from nutrient_totals, and conditions 'change how NIH reads a dose'. It also summarizes the four accepted product forms. It could have clarified servings defaults or the life_stage constraints, but the added semantics are substantive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource (checking a supplement stack for a person) and enumerates the concrete outputs: per-nutrient totals vs NIH UL/RDA-AI, product overlaps, UL rationale, and single-product fixes. That is well beyond a tautology. It stops short of a 5 because it never distinguishes itself from the sibling interactions_check, which also covers medication interactions, leaving a real ambiguity unresolved.
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 conditional guidance: pass medications and conditions to check interactions, use candidate products for 'considering adding', and use diet "typical" versus explicit foods. What is missing is exclusionary routing — no statement of when to call interactions_check or nutrients_reference instead, so sibling selection 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
interactions_checknutrients_referenceproducts_fda_reportsproducts_getproducts_lookupproducts_searchstack_analyzeCited supplement evidence, biomarker effects, interaction checks and brand quality
Supplement labels, doses against official upper limits, and a whole-stack check for overlaps.
Supplement safety for AI agents. 1,500+ rules, NIH+FDA data, quality grading A-D.
Dietary supplement register: compositions, country upper limits, US prices, stack check vs limits.
Add one secure layer between your agents and this server.