usda-mcp-server

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

Besides the readOnlyHint annotation, the description discloses that output is a structured markdown table, that all values scale to a gram basis, that missing FDC IDs are silently skipped, and that only too_few_foods is thrown when fewer than 2 are valid. This goes well beyond the annotations and adds useful behavioral context.

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, each with a distinct purpose: main function, output format, use cases, defaults and error handling. It is front-loaded with the primary verb and avoids any 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?

Given that an output schema exists, the description still covers return format, scaling, default nutrients, error behavior, and references to sibling tools. The description is self-sufficient for a complex comparison tool, with no significant 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?

The input schema already provides 100% coverage with detailed descriptions for every parameter, including the default nutrient list and the unit limitation. The description reinforces these (e.g., 'Omit nutrients[] to use defaults') but does not add substantial new information beyond what the schema already states.

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

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

The description opens with 'Compare nutrients side-by-side for 2–5 foods', a specific verb and resource scope. It further distinguishes from siblings by giving usage examples like 'spinach vs kale iron' and clarifies it is a comparison tool, not a retrieval (get) or search tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Best for' use cases, which indicates when to use. It also directs users to 'usda_search_foods to discover IDs' and 'usda_list_nutrients to look up other IDs', naming alternatives and providing actionable guidance for related tools.

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

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

Beyond the readOnlyHint annotation, the description explains key behaviors: per-100g default, optional scaling to specified portions, serving-weight interpretation, and nutrient filtering. It also clarifies the output as scaled nutrient values without contradictions to the annotation, adding substantial transparency.

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 concise yet comprehensive, front-loading the main purpose and then layering usage details. Each sentence adds value: ID discovery, scaling examples, and optimization tip. No wasted 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?

For a tool with 4 parameters and complex scaling/filtering behavior, the description covers all essential aspects: what is returned, how to scale portions, how to filter nutrients, and how to find IDs. The presence of an output schema and read-only annotation further complete the picture, so the description is fully adequate.

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 input schema already provides detailed descriptions for all parameters (100% coverage). The description adds a concrete example (quantity=200, unit='g') and explains the 'serving' unit's meaning, enriching the parameter semantics beyond the schema. However, much of what it says repeats schema content, so it does not fully transcend the baseline.

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

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

The description clearly states the tool gets the full nutrient profile for one food by FDC ID, using a specific verb and resource. It distinguishes from siblings by emphasizing 'one food' and referencing usda_search_foods for ID discovery, setting it apart from get_foods or compare_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?

It explicitly instructs to use usda_search_foods for discovering FDC IDs, which is a clear prerequisite. It also provides guidance on using nutrients[] to reduce response size and scaling via quantity/unit, though it does not explicitly contrast with usda_get_foods for multiple foods or compare_foods for comparisons. Overall, good practical guidance.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral details: per-100g units, no portion scaling, and failed IDs reported in failed[] rather than aborting the batch. This provides valuable context beyond the structured 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 four sentences, each with a distinct purpose: main function, efficiency rationale, unit caveat, and error handling. It is front-loaded and avoids 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 and only two parameters, the description covers batch behavior, failure handling, and units, making it sufficient for an agent to invoke correctly. It also names related tools for alternative use cases.

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?

Both parameters have descriptions in the schema (fdcIds and nutrients), so schema coverage is 100%. The description reinforces the recommendation to use nutrients[] but doesn't add new parameter-level semantics beyond the schema.

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

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

Description states 'Fetch nutrient profiles for 2–20 foods in a single API call,' providing a specific verb, resource, and batch scope. It also distinguishes from siblings by mentioning usda_compare_foods and usda_get_food.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly notes this is more efficient than calling usda_get_food N times and names usda_compare_foods as the alternative for side-by-side tables. Also recommends using the nutrients[] filter, giving clear context for when to use.

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

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

Annotations already indicate read-only and closed world. The description adds valuable behavioral context beyond annotations: the data is static, so it can be called once and cached. This goes beyond what annotations provide and helps the agent plan efficient usage.

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 sentences, each earning its place: first defines the tool's output, second gives a concrete use case, third provides a performance-relevant tip. No filler, front-loaded with the core purpose.

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 list tool with one optional parameter, output schema, and readOnly annotation, the description fully covers purpose, usage, and static nature. There is nothing missing for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% with a detailed enum and description. The description repeats the 'filter by category' behavior and adds 'narrow results,' but adds little new meaning beyond the well-documented parameter. Baseline of 3 is appropriate for high schema coverage.

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

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

The description opens with a specific verb+resource: 'Look up the FDC nutrient reference table' and enumerates exactly what it returns (IDs, names, SR reference numbers, units, categories). It clearly distinguishes itself from sibling food-search tools by focusing on the nutrient reference table.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'resolve a nutrient name to its FDC ID before passing it to the nutrients[] filter on other tools.' Also explains the optional category filter and advises reuse due to static data, giving clear usage context without needing to name alternatives.

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

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

Annotations declare readOnlyHint and openWorldHint, and the description adds meaningful nuance: the nutrient preview is "not guaranteed complete," and dataType defaults are conditional on brandOwner. This goes beyond the annotations to reveal behavior that could affect interpretation of results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately long but every sentence serves a purpose: purpose, return value, sibling links, default behavior, and branded search examples. It is front-loaded and well-organized, though slightly dense for scanning.

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

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

With an output schema present, the description focuses on usage scenarios, defaults, and alternatives, which it covers thoroughly. It does not mention pagination behavior but the schema already documents pageSize and pageNumber, so that gap is acceptable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the interplay between dataType and brandOwner, and by mentioning that UPC/GTIN codes can be used as queries for branded products — context not fully present in the schema descriptions.

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

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

The description opens with a specific verb and resource: "Search USDA FoodData Central foods by keyword." It clearly states what is returned (matching foods with FDC IDs and a nutrient preview) and differentiates from siblings by directing users to usda_get_food for full profiles and usda_compare_foods for comparisons.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is given for using the returned fdcId with usda_get_food and usda_compare_foods. It also explains when dataType defaults to SR Legacy vs Branded, when to set dataType to Branded, and how brandOwner narrows results — providing clear context for selection.

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