Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@USDA FoodData Central MCP Server Search for 'quinoa' and show its macros per 100g"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol (MCP) server that exposes USDA FoodData Central search and lookup tools. Plug it into Codex CLI, Claude Desktop, or any MCP-aware client to explore nutrition data without writing HTTP calls by hand.
Last README sync: base commit 7dede6c (update after next commit).
Four ready-to-use tools wrapping FoodData Central search, single-record lookup, bulk lookup, and paginated listing.
Strict validation with Zod schemas for inputs and outputs so LLMs can rely on structured results.
Cursor-aware previews let you dry-run calls, request compact summaries, and opt into raw payloads only when needed.
Lean nutrient lookups surface per-100 g calories, macros, saturated fat, and fiber through focused tools that accept just an FDC ID.
Resilient HTTP client with throttling, timeouts, and exponential backoff retries for USDA rate limits.
Built-in environment resource that describes the server configuration from inside your MCP client.
Related MCP server: Food Data Central MCP Server
Node.js 18.19 or newer (Claude Desktop’s bundled Node works).
USDA FoodData Central API key — request one at https://fdc.nal.usda.gov/api-key-signup.html and provide it via USDA_API_KEY.
git clone <repo-url>
cd USDA-mcp
npm install
cp .env.example .env
echo "USDA_API_KEY=your-key" >> .env
npm run start # runs via tsx with stdio transportThe server exits immediately if USDA_API_KEY is missing or blank. When you hand the server off to an MCP client, have that client supply the variable instead of relying on .env.
To run the compiled CLI (needed for Codex autostart):
npm run build
npx usda-mcp # assumes USDA_API_KEY is exported or supplied by the client
# Optional: install the CLI globally so `usda-mcp` is on your PATH
# npm install --global .
# (or run `npm link` inside the repo)Environment variables read at startup:
Variable | Required | Default | Purpose |
| Yes | — | FoodData Central API key; server exits if unset. |
| No |
| Override when routing through a proxy or staging host. |
You can provide these through .env, your shell, or the MCP client configuration. Use the config://usda-fooddata/environment resource to inspect the active settings from inside the client.
Most MCP clients let you attach environment variables directly to a server definition. Provide USDA_API_KEY there so the USDA server runs regardless of your working directory. Only set USDA_API_BASE_URL when you need to hit a non-default endpoint.
~/.config/codex/config.toml)Codex profiles accept per-server environment variables in TOML (Codex configuration guide).
Use whichever command style matches your setup:
command = "usda-mcp" if you ran npm install --global . (or npm link) so the CLI is on your PATH.
command = "node" with args = ["/absolute/path/to/dist/server.js"] if you prefer not to install the package globally.
experimental_use_rmcp_client = true
[mcp_servers.usda_fooddata]
command = "usda-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60
# If the CLI is not on your PATH:
# command = "node"
# args = ["/Users/you/projects/USDA-mcp/dist/server.js"]
[mcp_servers.usda_fooddata.env]
USDA_API_KEY = "your-fooddata-central-key"
# Optional override if you proxy the API:
# USDA_API_BASE_URL = "https://api.nal.usda.gov/fdc/v1/"claude_desktop_config.json)Claude Desktop reads server definitions from ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (see the MCP introductory docs for the format). Point to your built entry point and inject the key via env.
{
"mcpServers": {
"usda": {
"command": "node",
"args": ["/Users/you/projects/USDA-mcp/dist/server.js"],
"env": {
"USDA_API_KEY": "your-fooddata-central-key"
// "USDA_API_BASE_URL": "https://api.nal.usda.gov/fdc/v1/"
}
}
}
}Re-run npm run build whenever you change the server so dist/server.js stays in sync.
~/.cursor/mcp.json)Cursor keeps MCP definitions in ~/.cursor/mcp.json. Any server listed under mcpServers can set env (many server READMEs, including Yandex Search, use the same layout).
{
"mcpServers": {
"usda-fooddata": {
"type": "stdio",
"command": "node",
"args": ["/Users/you/projects/USDA-mcp/dist/server.js"],
"env": {
"USDA_API_KEY": "your-fooddata-central-key"
},
"startupTimeoutMs": 20000,
"toolTimeoutMs": 60000
}
}
}settings.json){
"mcpServers": {
"usda-fooddata": {
"command": "node",
"args": ["/Users/you/projects/USDA-mcp/dist/server.js"],
"env": {
"USDA_API_KEY": "your-fooddata-central-key"
},
"timeout": 20000
}
}
}settings.json)Gemini CLI merges MCP servers from system, user, and workspace settings (Gemini CLI configuration).
{
"mcpServers": {
"usda-fooddata": {
"command": "node",
"args": ["/Users/you/projects/USDA-mcp/dist/server.js"],
"env": {
"USDA_API_KEY": "your-fooddata-central-key"
},
"timeout": 30000
}
},
"mcp": {
"allowed": ["usda-fooddata"]
}
}All tools return a plain-text summary plus a structuredContent payload with a summary object, compact previews, and (when requested) the raw USDA response. Use the preview and dry-run switches to conserve context until you know you need the full payload.
search-foods – Full-text search that only surfaces the food description, optional brand/data type, and fdcId so agents can pick an entry without excessive detail. Filters, cursor pagination, sort controls, and dry-run previews help shrink context impact.
get-food – Fetch a single FoodData Central (FDC) record by ID with optional format and nutrients filters. Requests default to the faster USDA “abridged” view; the summary highlights macros (when present) and any notable gaps in the response. When USDA retires a known legacy identifier (e.g., SR Legacy 4053 for olive oil), the tool automatically substitutes the documented replacement (Foundation 748608 in this case) and adds a note so you know why the ID changed.
get_categories – Return category tags for a single FDC entry, including foodCategory (Foundation/SR Legacy), brandedFoodCategory (Branded), and wweiaFoodCategory (Survey/FNDDS) when present. The structured payload lists each category with its source and any available IDs/codes so you can cluster or filter foods by USDA taxonomy instead of text search alone.
get_macros – Return per-100 g calories, protein, fat, and carbohydrates for a single FDC entry with structured nutrient metadata. The helper first issues an abridged request scoped to the macro nutrient IDs, escalates to format=full, retries again without any nutrient filter, and finally consults labelNutrients (including Foundation-style labels such as Energy, Total fat (NLEA), and Total carbohydrate (NLEA)). If a Foundation record still withholds even one macro after that sequence, the tool now errors with guidance so you can pick a different FDC entry or compute the numbers manually (e.g., 1 g fat ≈ 9 kcal).
get_micros – Surfaces per-100 g vitamins and minerals (Calcium, Iron, Potassium, Sodium, Magnesium, Zinc, Vitamins A/C/D/E/K, Folate, Vitamins B6/B12). The helper runs through the same nutrient escalation/label parsing path, so most USDA foods return micronutrients without extra work.
get_macro_micros – Combines both panels so you can fetch calories, macros, and the vitamin/mineral set in one call (useful when you would otherwise chain get_macros + get_micros back-to-back).
get_fats, get_protein, get_carbs, get_kcal, get_satfats, get_fiber – Single-nutrient lookups that emit just the requested per-100 g value (or note that it is unavailable) to keep tool output distinct.
get-foods – Bulk lookup for up to 50 FDC IDs in one call. Supports previewOnly, includeRaw, sampleSize, and estimateOnly so you can review lightweight previews before retrieving the full objects, defaults to the faster USDA “abridged” format, and flags any requested IDs the USDA API omits. Known legacy → replacement mappings (e.g., 4053 → 748608) are applied automatically and noted in the summary.
list-foods – Deterministic paginated listing that accepts optional filters (data types, brand owner), cursor-based pagination, sort, and the same preview/dry-run switches as search-foods. The summary returns the next cursor only when another page is likely available.
list_portions – List USDA-defined portions for a single FDC entry (when available), including the human-readable portionDescription (for example “1 cup”), amount, gramWeight, and the associated measureUnit. Use this to translate per-100 g nutrient panels into serving-based numbers without re-parsing the raw foodPortions array yourself.
macros_for_portion – Given an fdcId and either a portionId or zero-based portionIndex (as returned by list_portions), compute calories, protein, fat, and carbohydrates for that USDA-defined portion. The tool enforces the same Foundation safeguards as get_macros (errors when macros are hidden), notes when a portion is missing gramWeight, and returns both per-100 g values and valuePerPortion in the structured nutrient list.
Foundation datasets sometimes omit energy, protein, or carbohydrate rows entirely (pure oils often only list lipid chemistry). The macro helper therefore:
Requests the abridged payload scoped to the calorie/protein/fat/carbohydrate nutrient IDs.
Falls back to format=full so USDA can include “analysis only” nutrients.
Retries the abridged call without nutrient filters so the API can decide which nutrients to include.
Reads labelNutrients, including Foundation label names such as Energy (kcal), Total fat (NLEA), Protein (NLEA), and Total carbohydrate (NLEA) even when USDA exposes those values only under display-friendly keys.
If any macro is still missing and the entry’s dataType is Foundation, get_macros stops with an error that lists the missing fields and suggests either switching to a record that publishes macros (e.g., SR Legacy or Survey entries) or deriving them yourself. A quick rule of thumb: calories ≈ (fat_g * 9) + (protein_g * 4) + (carbs_g * 4). Some oils (including FDC 748608) still omit USDA-provided calories/protein/carbs entirely across abridged/full/label payloads—this is a USDA database gap, not an MCP parsing bug—so keep the manual derivation handy for edge cases that never expose those fields.
Need both macro and micronutrient panels simultaneously? Call get_macro_micros to collapse the workflow into a single USDA request. It enforces the same Foundation guard for missing macros, surfaces micronutrient gaps in the summary, and automatically falls back to an unfiltered USDA fetch if the combined nutrient filter list exceeds USDA’s request limit (so you still get data, just with a slightly larger payload).
get_micros)USDA keeps dozens of micronutrients in FoodData Central. The get_micros tool focuses on the vitamins and minerals that appear on standard nutrition labels so agents can request them in one call. Each value is per 100 g and travels through the same abridged/full/label fallback path used by get_macros.
Nutrient | Unit | USDA nutrient IDs (abridged/full) | Label aliases |
Calcium | mg | 1087, 301 |
|
Iron | mg | 1089, 303 |
|
Potassium | mg | 1092, 306 |
|
Sodium | mg | 1093, 307 |
|
Magnesium | mg | 1090, 304 |
|
Zinc | mg | 1095, 309 |
|
Vitamin A (RAE) | mcg | 1104, 318 |
|
Vitamin C | mg | 1162, 401 |
|
Vitamin D (D2 + D3) | mcg | 1114, 324, 328 |
|
Vitamin E (alpha-tocopherol) | mg | 1109, 323 |
|
Vitamin K (phylloquinone) | mcg | 1185, 430 |
|
Folate, total | mcg | 1186, 417 |
|
Vitamin B6 | mg | 1175, 415 |
|
Vitamin B12 | mcg | 1178, 418 |
|
If a micronutrient is absent from both the nutrient list and labelNutrients, the response lists it under summary.notes so downstream automation can decide whether to fall back to manual data.
get_macro_micros returns this entire table plus the macro set in one result, so you can minimize USDA round-trips when you know you need the full panel.
config://usda-fooddata/environment – Markdown overview showing the active base URL, whether a key is detected, retry/throttle policies, and guidance for overrides.
usda_rebuild_progress.md – Workspace log for ingredient coverage. Record every “no USDA equivalent” decision (for example, ground sumac lacks a generic record, so we either keep the branded FDC 2630657 macros or stay with the manual rollup) to prevent repeated lookups.
Requests time out after 30 seconds, use up to two retries with jittered exponential backoff on HTTP 429 or 5xx, and throttle to one concurrent call with ≥400 ms spacing so we stay under the 3 requests/second USDA ceiling. When USDA asks for a longer pause (via Retry-After), that guidance is surfaced in the error text.
Handle USDA rate limits responsibly: use narrow filters, reuse previous results, and avoid large bulk queries unless necessary.
Missing or invalid API keys cause the server to log the issue and exit immediately so MCP clients can surface the error.
Nutrient helpers follow a strict escalation path (scoped abridged → format=full → unfiltered abridged → labelNutrients) and recognise alternate labels such as Total fat (NLEA) so oils and other sparse entries still return macro values. When a Foundation record still hides any macro after those retries, get_macros intentionally errors and points you to alternate FDC IDs or the calorie conversion formula so downstream automations do not ingest partial data unknowingly.
Legacy SR Legacy identifiers that USDA has retired (currently 4053 for olive oil) are automatically mapped to their documented replacement IDs, and every substitution is called out in the tool summaries (plus requestedFdcIds in the preview payload) so downstream automations can update their catalogs.
Some pantry staples still lack a generic SR Legacy or Foundation record. To avoid thrashing the USDA API:
Search for the closest USDA record and document the FDC ID you plan to use (even if it is branded). Ground sumac does have a viable entry—use FDC 2630657 (branded) and record that choice in usda_rebuild_progress.md so other contributors know it is the canonical pick until USDA publishes a generic version.
When no acceptable record exists (for example, composite spice mixes that include salt), log the ingredient in usda_rebuild_progress.md under “No USDA equivalent” with the reasoning and the manual macro source. That file now serves as the go/no-go list before you spend time retrying lookups.
If you later discover a matching USDA record, update the log with the new ID and remove the “no equivalent” flag so future rebuilds revisit the ingredient.
npm run start – Launch with tsx for local development.
npm run lint – Type-check the TypeScript sources (tsc --noEmit).
npm run build – Emit the compiled bundle to dist/ for the CLI or packaging.
Run npm run build whenever you change server code and want Codex or other clients that call usda-mcp to pick up the new build.
Startup fails: missing API key – Ensure USDA_API_KEY is exported in your shell or supplied through the MCP client config.
Client connects but requests fail with 401/403 – Verify the key is active and not rate-limited on the USDA side.
Repeated 429 Too Many Requests – Each tool already slows calls to one at a time; if you still get 429 responses, wait for the Retry-After duration shown in the error text or batch IDs into fewer round-trips.
Legacy FDC ID returns “not found” – USDA periodically retires SR Legacy entries. Known substitutions (currently 4053 → 748608 for olive oil) are applied automatically and annotated in the tool response; otherwise, use search-foods to locate the modern FDC ID.
Foundation macros come back empty – get_macros escalates through full/unfiltered calls plus labelNutrients, including Foundation display labels such as Energy (kcal) and Total fat (NLEA). When a record still hides macros after that sweep, the tool errors with the missing fields. Pick another FDC ID that exposes macros (SR Legacy or Survey datasets usually do) or estimate calories via (fat_g * 9) + (protein_g * 4) + (carbs_g * 4) (oils generally have protein/carbs = 0). FDC 748608 is a known USDA data gap: only the fat numbers are published, so manual macros are required.
Micronutrients missing – get_micros reports which vitamins/minerals are unavailable in summary.notes. That usually means the USDA record never published the nutrient; check get-food for the raw payload or substitute a richer FDC ID if you need the value.
No generic entry for an ingredient (e.g., ground sumac) – Document the decision in usda_rebuild_progress.md. Ground sumac uses branded FDC 2630657 as the accepted entry today; for other ingredients without an acceptable record, note the manual macros and rationale so contributors avoid duplicate searches.
CLI warns about missing dist/server.js – Run npm run build before invoking npx usda-mcp.
For API reference, see the official FoodData Central guide: https://fdc.nal.usda.gov/api-guide.html
Return per 100 g carbohydrates for a FoodData Central entry. Returns a single value per 100 g to minimize context usage.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| nutrient | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds that the tool returns a single value per 100 g, clarifying output cardinality and unit, which is useful behavioral context beyond the structured annotations. No contradiction exists.
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 description is two sentences with front-loaded purpose: the first sentence states what it does, the second explains the output format and rationale. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema present, the description covers the essential behavior: returns a single carbohydrate value per 100 g. It could mention error cases, but the tool is so focused that the current level is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema defines fdcId as a positive integer but provides no description (0% coverage). The description says 'for a FoodData Central entry', implicitly identifying fdcId as the entry identifier, but it doesn't explicitly map the parameter name to the concept. This is adequate but minimal.
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 clearly states the tool returns per 100 g carbohydrates for a FoodData Central entry. The verb 'Return' and specific resource 'carbohydrates' distinguish it from sibling tools like get_macros or get_protein, especially with the per-100g qualification.
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 'Returns a single value per 100 g to minimize context usage' implies when to use this tool: when only carbohydrate data is needed and minimal output is desired. It doesn't explicitly name alternatives, but the context is clear enough for an agent to select this over broader nutrient tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return category tags for a FoodData Central entry, including FoodCategory, brandedFoodCategory, and WweiaFoodCategory when available.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| categories | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral context by noting fields are returned 'when available,' which informs the agent about potential absent 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?
The description is a single, front-loaded sentence with no wasted words. It states the action, target, and return fields efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only lookup with one parameter and an output schema, the description is sufficiently complete. It covers what the tool returns, the domain context, and the optional presence of specific fields, while annotations and schema handle the rest.
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 0%, but the description compensates by identifying the object as a 'FoodData Central entry,' which gives conceptual meaning to the fdcId parameter. It doesn't explicitly explain the parameter's role, but the single required integer parameter is self-explanatory enough.
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 uses the specific verb 'Return' with the resource 'category tags for a FoodData Central entry' and names the exact fields included. This clearly distinguishes it from sibling tools focused on nutrients and food 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?
The description does not state when to prefer this tool over siblings or provide any exclusions. While the purpose implies use when category tags are needed, there is no explicit usage context or mention of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return per 100 g total fat for a FoodData Central entry. Returns a single value per 100 g to minimize context usage.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| nutrient | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint, and the description adds valuable behavioral context by stating the return is a single value per 100 g, which clarifies output shape and rationale (context efficiency). This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, front-loaded with the key action and resource. Every word adds value, and the structure is appropriately minimal for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema present, the description covers the essential behavioral and outcome aspects (single value, per 100 g, minimizes context). No gaps that hamper proper use.
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 zero schema description coverage, the description carries the burden but only indirectly explains fdcId as 'a FoodData Central entry.' It doesn't explicitly state that fdcId is the identifier or provide format details, though the single parameter is self-explanatory given the tool name and context.
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 clearly states a specific verb ('Return'), resource ('FoodData Central entry'), and the data returned ('per 100 g total fat'). It distinguishes itself from sibling nutrient-specific getters by emphasizing the single value per 100 g, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when needing total fat per 100 g) and mentions 'to minimize context usage,' which hints at a benefit over more comprehensive tools. However, it does not explicitly name alternatives or state when not to use it, leaving the comparison to the user.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return per 100 g dietary fiber for a FoodData Central entry. Returns a single value per 100 g to minimize context usage.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| nutrient | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds valuable behavioral context by specifying that the return is a single per-100g value, which helps the agent anticipate the output shape and size. This goes beyond the annotations by explaining the tool's efficiency-focused design.
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 description is two sentences long, with the core purpose in the first sentence and a justification for the tool's design in the second. There is no unnecessary information, and it is well-structured for quick parsing.
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?
The tool is simple with one parameter, has an output schema, and annotations already provide safety information. The description adds the key behavioral detail of returning a single per-100g value for context efficiency, making the tool's behavior fully specified for an agent to invoke 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?
The schema has only one parameter, fdcId, with type and constraints but no description (0% coverage). The description mentions 'FoodData Central entry,' which implicitly indicates fdcId is the FoodData Central ID, but does not explicitly state this. Given the single parameter and the contextual clue, the description provides partial compensation but could be more explicit.
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 clearly states the tool returns per-100g dietary fiber for a FoodData Central entry, using the verb 'Return' and specifying the measurement unit. It distinguishes itself from sibling tools by naming the exact nutrient (dietary fiber) and emphasizing the single-value output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool returns a single value per 100 g to minimize context usage, which implies it should be used when only dietary fiber is needed and other nutrients are not required. It does not explicitly mention alternatives, but the context is clear and sufficient for selecting this tool over siblings that return broader nutrient profiles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a single FoodData Central (FDC) record by numeric ID. Supports abridged/full detail toggles and nutrient ID subsets to trim responses. Ideal once you already know the identifier.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes | ||
| format | No | ||
| nutrients | No | List of nutrient IDs to include (per API documentation). |
| Name | Required | Description |
|---|---|---|
| food | Yes | |
| macros | No | |
| summary | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description does not need to restate safety. It adds valuable behavioral context by mentioning 'abridged/full detail toggles' and 'nutrient ID subsets to trim responses', which informs the agent about response-size control—something not present in the annotations.
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 description is three sentences: purpose, feature summary, and usage context. Every sentence provides unique value with no redundancy. It is front-loaded with the primary action and stays under 30 words.
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?
The tool is a simple single-record lookup with an output schema present. The description covers purpose, use case, parameter semantics, and behavior (response trimming). Given the low complexity and the presence of an output schema, no further details are necessary for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only 'nutrients' has a description). The description compensates by implicitly defining 'fdcId' as a numeric ID, 'format' as an abridged/full toggle, and 'nutrients' as ID subsets for trimming. This adds meaning for all three parameters, though it does not specify exact formats or constraints.
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 uses a specific verb ('Look up') and resource ('single FoodData Central (FDC) record') and explicitly notes 'by numeric ID', which distinguishes it from sibling search/list tools. The phrase 'Ideal once you already know the identifier' clarifies its scoped use, making it impossible to confuse with search-foods or list-foods.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states a clear usage condition: use when you already know the identifier. This implies search tools are for unknown IDs, though it does not explicitly name alternatives or provide when-not-to-use rules. It is strong guidance but stops short of a full exclusionary set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Batch lookup for multiple FDC IDs via the USDA bulk endpoint. Provide up to 50 IDs to reduce repeated network calls. Supports abridged/full detail and nutrient filters per the API.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcIds | Yes | ||
| format | No | ||
| nutrients | No | List of nutrient IDs to include (per API documentation). | |
| includeRaw | No | ||
| sampleSize | No | ||
| previewOnly | No | ||
| estimateOnly | No |
| Name | Required | Description |
|---|---|---|
| foods | No | |
| summary | Yes | |
| previews | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, repeatable read operation. The description adds 'reduce repeated network calls' as an efficiency note but doesn't disclose additional behavioral traits like rate limits, error behavior, or external API dependencies beyond the vague 'per the API.' It meets the baseline but doesn't exceed it.
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 description is two sentences, front-loaded with the primary purpose, and every clause adds value. No wasted words, and it covers the key capability, batch limits, and filter options efficiently.
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 tool with 7 parameters and low schema coverage, the description provides a clear high-level overview but omits the behavior of several optional flags. The existence of an output schema covers return values, but the missing parameter semantics create a significant gap in understanding how to configure the call. It's adequate for the core use case but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 14% (only 'nutrients' has a description). The description explains a few parameters (fdcIds, format, nutrients) but leaves four parameters (includeRaw, sampleSize, previewOnly, estimateOnly) entirely unexplained. With such low schema coverage, the description must compensate by clarifying all parameters, but it only covers about half, leaving the agent guessing about the other options.
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 clearly states a specific verb+resource: 'Batch lookup for multiple FDC IDs via the USDA bulk endpoint.' It distinguishes itself from siblings like get-food (singular) and list-foods by emphasizing the batch capability and bulk endpoint, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: 'Provide up to 50 IDs to reduce repeated network calls.' This explains the advantage over repeated single lookups, though it doesn't explicitly name alternatives or state when not to use it. The context is clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return per 100 g calories for a FoodData Central entry. Returns a single value per 100 g to minimize context usage.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| nutrient | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds useful context by specifying the return is a single value per 100 g and that this design minimizes context usage, which explains the output size and 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 sentences, front-loaded with the core purpose, and every word earns its place. No redundancy or 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?
For a low-complexity tool with one parameter and an output schema, the description covers the essential return value and unit. Annotations cover safety, so no major gaps remain. Minor missing details about error cases are not critical here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does by relating fdcId to a FoodData Central entry, providing minimal semantic context. However, it lacks details like how to obtain fdcId or how invalid IDs are handled.
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 exactly what the tool does: 'Return per 100 g calories for a FoodData Central entry.' It is specific with a clear verb and resource, and the 'single value per 100 g' detail distinguishes it from broader macro tools like get_macros or get_fats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when only calorie information is needed, and 'to minimize context usage' suggests a lightweight alternative. However, it does not explicitly name alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return per 100 g macro plus vitamin/mineral panels for a FoodData Central entry.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| nutrients | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description adds context by specifying the per-100g normalization and indicating the data source is a FoodData Central entry. This is useful behavioral information beyond the schema, though it doesn't cover error cases. With strong annotations, this is sufficient.
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 description is a single, well-structured sentence with no wasted words. It front-loads the action and includes all key details (per 100g, macro plus micro panels, FoodData Central entry).
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 a low-complexity one-parameter tool, strong read-only/idempotent annotations, and a known output schema, the description is complete for its purpose. It clearly states what is returned and the unit, and the output schema covers return structure. Nothing essential 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 0%, so the description must compensate for the single 'fdcId' parameter. It does so implicitly by referencing 'FoodData Central entry', making it clear fdcId is the entry's identifier. However, it doesn't explicitly define the parameter or mention its format/constraints beyond the schema's exclusiveMinimum. This is adequate but not exceptional.
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 clearly states the tool returns per-100g macro and vitamin/mineral panels for a FoodData Central entry, using a specific verb ('Return') and resource ('FoodData Central entry'). This distinguishes it from siblings like get_macros and get_micros by making clear it combines both, and the per-100g unit adds useful specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need both macro and micro panels for a food entry) but does not explicitly state alternatives or exclusions. It doesn't say 'use get_macros for only macros' or 'avoid this if you need just one panel.' Thus it provides clear context but no explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return per 100 g calories, protein, total fat, and carbohydrates for a FoodData Central entry.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| nutrients | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds the important detail that values are normalized per 100g, but it does not disclose edge cases like missing data, zero values, or error handling.
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 description is a single sentence, front-loaded with the verb, and contains no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one input) and has an output schema, so the description need not spell out return fields. It adequately covers the core functionality and per-100g normalization. However, it lacks a usage note referencing sibling tools, which would improve completeness given the many alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a single required fdcId with no description (0% schema coverage). The description references 'a FoodData Central entry' but does not explicitly define fdcId as the entry identifier or explain its format, though the context from the tool name and schema makes the intent clear.
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 clearly states the action (Return) and resource (FoodData Central entry) with specific nutrients (calories, protein, fat, carbs). It distinguishes itself from sibling tools by returning a combined macro set rather than a single nutrient.
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 usage is implied: use this tool when needing the standard per-100g macro profile. However, there is no explicit guidance on when to prefer this over alternatives like get_protein or get_micros, which are present in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return per 100 g vitamins and minerals for a FoodData Central entry (Calcium through B vitamins).
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| nutrients | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only and idempotent behavior, so the description adds value by specifying the 'per 100 g' normalization and the nutrient range. This gives the agent important context about the output format without contradicting any annotations.
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 description is a single, compact sentence that is front-loaded with the core action and resource. Every word earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter tool, the description sufficiently covers the tool's purpose and output scope. The presence of an output schema means return value details don't need to be described, and the per 100g basis plus nutrient range provides the necessary context.
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 0% schema coverage, the description must compensate. It does mention 'a FoodData Central entry', which implies fdcId identifies the entry, but it doesn't provide explicit detail about how the parameter is used or validated. The schema already specifies integer type and positive constraint, so the description adds minimal semantic value.
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 clearly states a specific action ('Return') and resource ('vitamins and minerals for a FoodData Central entry'), distinguishing it from sibling tools focused on macros or other nutrient groups. The parenthetical '(Calcium through B vitamins)' further clarifies the exact scope of micronutrients covered.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving micronutrient data per 100g, providing clear context for when to use it. It does not explicitly mention alternatives like get_macros or get_macro_micros, but the purpose is unambiguous enough that an agent could infer the appropriate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return per 100 g protein for a FoodData Central entry. Returns a single value per 100 g to minimize context usage.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| nutrient | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent behavior, so the bar is lower. The description adds useful operational details: per-100g normalization and single-value return, which go beyond annotations. It doesn't cover error handling, but for a simple read tool this is acceptable.
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 concise sentences with front-loaded behavior in the first sentence and a rationale in the second. Every word earns its place; no redundancy or 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 an output schema present and annotations covering safety, the description is sufficient for a simple data-retrieval tool. It explains the unit and response shape, though it doesn't mention missing-data behavior. Given the simplicity, the absence is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one required parameter fdcId with 0% description coverage. The parameter name is self-explanatory, and the description clarifies it refers to a FoodData Central entry, but adds no extra detail about the ID format, source, or constraints beyond the schema's exclusiveMinimum.
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?
Description clearly states the tool's verb (return) and resource (per 100g protein for a FoodData Central entry), distinguishing it from sibling tools focused on other nutrients. The 'per 100 g' scope is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions the benefit of minimizing context usage, which implies a use case over broader tools like get_macros or get-food, but does not explicitly name alternatives or state when not to use it. The context is clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return per 100 g saturated fat for a FoodData Central entry. Returns a single value per 100 g to minimize context usage.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| nutrient | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds meaningful context beyond the readOnly and idempotent hints by disclosing the per-100g basis and the single-value output design to minimize context. It does not contradict the annotations and avoids unnecessary details for a simple read operation.
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 concise sentences front-load the core behavior and intent, with no redundant words. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, a known output schema, and read-only/idempotent annotations, the description sufficiently covers the essential behavior and purpose. The output format is left to the schema, which is appropriate.
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 only parameter fdcId is self-explanatory, but with 0% schema description coverage, the description does not explicitly explain what fdcId represents or how to obtain it. The phrase 'for a FoodData Central entry' implies the ID refers to an entry, but that is indirect and minimal.
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 it returns saturated fat per 100g for a FoodData Central entry, a specific verb-resource pair that clearly distinguishes it from siblings like get_fats or get_macros. The per-100g normalization is explicit and useful.
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?
Implicitly indicates use when only saturated fat is needed, and the phrase 'to minimize context usage' provides a rationale for selecting this tool over more comprehensive ones. However, it does not explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Page-oriented listing endpoint for predictable iteration when you already know the data type or brand. Supports pagination, sorting, and brand filters, returning summaries for quick scanning.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort configuration for listing results. | |
| filters | No | Optional filters to scope the deterministic listing endpoint. | |
| includeRaw | No | ||
| pagination | No | Pagination controls. Provide either page/size or cursor, not both. | |
| sampleSize | No | ||
| previewOnly | No | ||
| estimateOnly | No |
| Name | Required | Description |
|---|---|---|
| foods | No | |
| summary | Yes | |
| previews | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=false. The description adds value by disclosing that it returns summaries for quick scanning and supports predictable iteration, giving a sense of the response style and deterministic behavior without contradicting the annotations.
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 description is a single, front-loaded sentence that packs the core purpose and key features without any filler. Every phrase contributes meaning, making it extremely efficient.
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 tool with 7 parameters and nested schemas, the description covers the primary listing use case and core features but omits several optional parameters that remain unexplained in both the description and schema. The presence of an output schema and annotations helps, but the parameter coverage gap makes this only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 43%, leaving includeRaw, sampleSize, previewOnly, and estimateOnly without descriptions in either the schema or the tool description. The description only rementions pagination, sorting, and brand filters, which are already documented in the schema, so it does little to illuminate the less obvious parameters.
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 clearly identifies this as a page-oriented listing endpoint for predictable iteration when the data type or brand is already known. It distinguishes itself from search-oriented siblings like search-foods by specifying a known-data scenario and by listing concrete capabilities (pagination, sorting, brand filters).
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 'when you already know the data type or brand' provides clear context for when this tool is appropriate, implying it should not be used for open-ended searches. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full exclusion/alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return labeled portion sizes for a FoodData Central entry, including gram weights when available.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| portions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint, so safety is covered. The description adds the nuance that gram weights are returned 'when available', which is useful but minimal. No extra details about output structure or edge cases, though an output schema exists.
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 description is a single, focused sentence that front-loads the action and resource. No filler or redundant information; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter, an output schema, and strong annotations, the description is complete. It covers the core behavior and uses the output schema to handle return structure, requiring no further elaboration.
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 0% and the schema only lists fdcId with a type. The description implicitly explains that fdcId identifies a FoodData Central entry, giving meaning to the parameter. This is sufficient for a single-parameter tool, though not explicitly naming the parameter.
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 clearly states the tool's action ('Return') and resource ('labeled portion sizes for a FoodData Central entry'), with a specific qualifier ('including gram weights when available'). This is distinct from sibling tools that handle foods, nutrients, or categories, as it focuses specifically on portion sizes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you have an fdcId and need portion sizes, but it does not explicitly mention alternative tools (e.g., macros_for_portion) or provide exclusions. The context is clear but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return calories, protein, fat, and carbohydrates for a specific USDA-defined portion of a FoodData Central entry.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes | ||
| portionId | No | ||
| portionIndex | No |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| nutrients | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and idempotent behavior, so the safety profile is clear. The description adds no further behavioral details, such as how portionId vs portionIndex are resolved or error cases. It is sufficient but not enriching.
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 description is a single, front-loaded sentence that clearly states the action and result. No extra words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values are covered. However, the description does not explain which parameter to use under which circumstances, leaving ambiguity around portionId vs portionIndex. It is minimally complete for a read-only tool but misses crucial context for correct invocation.
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?
Input schema has 0% coverage and no descriptions. The description mentions 'FoodData Central entry' and 'USDA-defined portion', which loosely maps to fdcId and portionId/portionIndex, but does not explain the distinction between portionId and portionIndex or that fdcId is required. The description fails to fully compensate for the schema's lack of parameter documentation.
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 clearly states the tool returns calories, protein, fat, and carbohydrates for a specific USDA-defined portion of a FoodData Central entry. This distinguishes it from siblings like get_macros (which likely returns macros for a whole food entry) and list_portions (which lists portions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you need macro values for a specific portion rather than the entire food entry. It provides context but does not explicitly mention alternatives or when not to use it. The mention of 'USDA-defined portion' gives a clear use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search of USDA FoodData Central with structured filters, pagination cursors, preview mode, and dry-run estimation to conserve context.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort configuration. Omit or set by="relevance" for API defaults. | |
| query | Yes | ||
| filters | No | Optional filters to narrow the search results. | |
| includeRaw | No | ||
| pagination | No | Pagination controls. Provide either page/size or cursor, not both. | |
| sampleSize | No | ||
| previewOnly | No | ||
| estimateOnly | No |
| Name | Required | Description |
|---|---|---|
| raw | No | |
| summary | Yes | |
| previews | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnly and openWorld; the description adds that it has preview mode and dry-run estimation to conserve context, which is useful behavioral context. It does not mention rate limits, data freshness, or how preview/dry-run behave, but with annotations present this is adequate but not rich.
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?
Single, well-structured sentence front-loads the tool purpose and lists features without redundancy. It earns its place by adding the 'conserve context' rationale.
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 an 8-parameter tool with nested objects and low schema coverage, one sentence is insufficient. Output schema exists, but optional parameters like sampleSize and includeRaw remain unexplained, and the relationship between previewOnly and estimateOnly is ambiguous.
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 38% and the description does not explain the optional query, includeRaw, sampleSize, previewOnly, or estimateOnly semantics beyond naming the feature groups. It orients the agent that query is full-text and maps filters/pagination to concepts, but does not compensate for undocumented parameters.
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 clearly states it performs full-text search of USDA FoodData Central and lists key features. This distinguishes it from sibling list-foods and get-food tools by the 'full-text search' verb+resource pair, though it doesn't explicitly name alternative tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a search use case but provides no explicit when-to-use guidance or exclusions among sibling tools. It does not state that list-foods should be used for unfiltered listing or that get-food is for single-item retrieval.
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.
v1.1.0get_carbsget_categoriesget_fatsget_fiberget_kcalget_macro_microsget_macrosget_microsget_proteinget_satfatsget-foodget-foodslist_portionslist-foodsmacros_for_portionsearch-foodsScored across 16 tools
Several tools return overlapping nutrient data (e.g., get_macros, get_macro_micros, and individual get_kcal/get_protein/get_carbs/get_fats), which could lead an agent to select a broader or narrower result than needed. Descriptions are specific enough to disambiguate most cases, but the set is not fully distinct.
Tool names mix kebab-case (list-foods, search-foods, get-food, get-foods) with snake_case (get_macros, list_portions, macros_for_portion), violating the consistency rule. All use a verb_noun structure, but the hyphen/underscore split is unpredictable.
16 tools is at the edge of the comfortable range, and the many single-nutrient getters (get_kcal, get_protein, get_carbs, etc.) inflate the count without adding truly distinct capabilities. Still, the core search/lookup/portion workflows justify most of the tools.
For a read-only food database, the server covers discovery (search/list), retrieval (get-food/get-foods), nutrient breakdowns, and portions. No obvious dead ends; minor gaps like per-food-specific nutrient filtering for raw values are not needed since get-food supports nutrient subsets.
Search foods, compare nutrients, and look up the full USDA FoodData Central database.
Food and nutrition data: search, macros, and comparisons
USDA FoodData Central nutrition data: search foods, compare macros, and analyze meals.
Edamam MCP — wraps three Edamam APIs in one pack: