usda-mcp-server

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

Discloses output format (structured markdown table), scalar scaling to a gram basis, default nutrient list, and error handling (fallback behavior with invalid FDC IDs, only throwing too_few_foods). This adds substantial behavioral context beyond the readOnlyHint annotation, fully informing the agent of expected outcomes and edge cases.

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 paragraphs of dense but efficient prose, front-loaded with purpose and output format, then usage examples, defaults, scaling, and error behavior. Every sentence adds information, with no filler or repetition.

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 an output schema, the description covers all essential aspects: purpose, use cases, default behavior, parameter customization, scaling, and error handling. It references sibling tools for ID discovery, leaving nothing an agent needs to call it correctly.

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

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

Schema already covers all parameters (100% coverage), but the description adds valuable context: how to omit nutrients to use defaults, which defaults are included (listing them), how to discover FDC IDs (referencing sibling tools), and limitations of the unit parameter (no 'serving'). This enriches parameter understanding 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?

Clearly states the tool compares nutrients side-by-side for 2–5 foods and returns a markdown table. Distinguishes itself from siblings like usda_get_food (single food retrieval) and usda_search_foods (searching) by focusing on comparison, making the 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?

Provides explicit use cases ('spinach vs kale iron' or 'which has more protein?') and describes behavior when IDs are missing (proceeds with valid foods, throws only when fewer than 2). While it doesn't list exclusions, the sibling tools are clearly different, and the examples make when-to-use obvious.

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 provide readOnlyHint=true, and the description does not contradict it. The description adds substantial behavioral details beyond annotations: per-portion scaling mechanics, the meaning of unit='serving', the default per-100g basis, and the effect of omitting quantity. These are valuable behavioral specifications an agent needs to call correctly.

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, logically organized paragraph that front-loads the primary purpose and then layers supporting details: scaling, serving, and nutrient filtering. Every sentence conveys useful information without fluff. It is slightly longer than necessary but remains tight given the breadth of behavior covered.

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

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

For a read-only, single-food retrieval tool, the description is remarkably complete. It covers the return scope, filtering, scaling semantics, serving interpretation, and default behavior. It points to the correct sibling for ID discovery and implicitly differentiates from plural retrieval. There is no missing critical information for an agent to invoke correctly, especially with a rich output schema available.

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 all parameters are described in the schema. The description enriches these with practical semantics: fdcId discovery via search, quantity/unit scaling requirements, 'serving' behavior, and nutrient ID lookup via usda_list_nutrients. It goes beyond the schema's mechanical descriptions to explain usage 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?

States a specific verb and resource: 'Get the full nutrient profile for one food by FDC ID.' It clearly distinguishes from siblings like usda_get_foods (plural) by emphasizing 'one food' and mentions the optional filtering via nutrients[]. The primary function is unambiguous and stands apart from search, list, and compare tools.

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

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

Explicitly routes to usda_search_foods for discovering FDC IDs and explains when to use nutrient filtering to reduce response size. It does not explicitly mention when to prefer usda_compare_foods or usda_get_foods, but the singular-versus-plural distinction is implicit. Missing explicit exclusions, but the core usage is well-defined.

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 discloses key behavioral details: values are per 100g with no portion scaling, and failed IDs are returned in a failed[] array rather than aborting the batch. It also strongly recommends the nutrients filter to limit response size. This adds meaningful context beyond annotations and does not contradict 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?

The description is four sentences, each carrying essential information: core purpose, efficiency rationale, unit context, filter recommendation, alternative routing, and failure behavior. No redundancy; front-loaded with the primary action.

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 description covers the critical aspects: batch scope, units, failure handling, and recommended filter. An output schema exists (which would explain the success response shape), so its absence here is acceptable. Minor gaps like rate limits or behavior when all IDs fail are not covered, but these are not essential 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?

Both parameters are fully described in the schema (100% coverage), so the baseline is 3. The description reinforces the nutrients recommendation and adds efficiency context, but does not introduce additional format or semantic details for the parameters beyond what the schema already provides.

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 ('Fetch'), resource ('nutrient profiles'), and scope ('2–20 foods in a single API call'). It explicitly distinguishes itself from siblings by noting efficiency over usda_get_food and directing to usda_compare_foods for formatted tables, and references usda_search_foods and usda_list_nutrients for ID discovery.

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 clearly tells when to use this tool (batch of multiple FDC IDs, more efficient than repeated calls) and points to an alternative (usda_compare_foods for side-by-side tables). It also reinforces the recommended nutrients filter and warns against large responses. The 2–20 range is stated explicitly, covering the main constraint.

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 provide readOnlyHint=true and openWorldHint=false, so the description doesn't need to cover safety. It adds useful behavioral context: the data is static, so results can be cached and reused. This goes beyond the annotations and helps the agent plan calls efficiently.

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 with a distinct purpose: what it does, how to use it, and a caching hint. The most important information (purpose and usage) is front-loaded, followed by a practical note. 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?

For a tool with only one optional parameter and an output schema, the description is complete. It covers the purpose, usage context, filtering options, and data characteristics. Nothing an agent needs to call it correctly 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?

The schema covers 100% of the parameters, with a clear enum and description for 'category'. The description repeats the enum options and adds 'narrow results', but doesn't add new meaning beyond the schema. Baseline of 3 applies since schema does the heavy lifting.

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 verb ('Look up') and resource ('the FDC nutrient reference table'), and specifies exactly what it returns (numeric IDs, names, SR reference numbers, units, categories). It distinguishes itself from the food-related siblings by focusing on nutrients, and even provides a concrete example ('vitamin C' → 1162).

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 'Use to resolve a nutrient name ... before passing it to the nutrients[] filter on other tools,' which gives clear when-to-use guidance. It also suggests filtering by category and notes the static nature ('call once and reuse'). It doesn't explicitly mention when not to use it, but the context with siblings makes the differentiation obvious.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description is consistent with them (no contradiction). It adds valuable behavior beyond annotations: it warns that the nutrient preview is 'not guaranteed complete,' explains the default dataType logic (SR Legacy vs Branded based on brandOwner), and notes that only Branded records carry a brandOwner. This transparency about data completeness and default behavior exceeds what annotations alone provide.

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 dense with information but not bloated. It front-loads the core purpose and return value, then moves to downstream tool usage and defaults. Each sentence contributes new guidance. Slightly long but efficient; a score of 4 reflects that it could be slightly tightened without losing essential details.

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 output schema exists and the description already notes the returned nutrient preview (energy, protein, fat, carbs) and FDC IDs, an agent has enough to understand the call result. The description also covers defaults and edge cases (UPC codes, brandOwner) that are not evident from the schema alone. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful enhancements: it explains how the query parameter can also accept UPC/GTIN codes, and it details the interaction between dataType and brandOwner (that setting brandOwner defaults dataType to ['Branded'] unless explicitly overridden). This goes beyond the schema's static field descriptions, justifying a score above 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 states a specific verb ('Search'), a precise resource ('USDA FoodData Central foods'), and the input ('by keyword'). It also explains what is returned (matching foods with FDC IDs and a nutrient preview), and explicitly distinguishes itself from sibling tools by naming usda_get_food and usda_compare_foods as follow-ups. This fully establishes the tool's unique role.

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 provides explicit routing: 'Use the returned fdcId with usda_get_food for the full nutrient profile, or usda_compare_foods for side-by-side comparisons.' It also clarifies when to set dataType to ['Branded'] and how to use UPC/GTIN codes or brandOwner filters. These guidelines directly address selection against alternative tools and appropriate usage contexts, leaving no ambiguity.

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