Server Quality Checklist

Tool Scores

• search_foodsA
  3.8/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It adds useful behavior beyond the schema: it names return fields, reveals that Foundation records may omit Energy while SR Legacy has complete macros, and discloses that results are cached on disk. It does not mention auth or rate limits, but the disclosure of data caveats and caching is solid.

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

  Conciseness5/5

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

  Three sentences, front-loaded with the core purpose, then specific return fields and a data-quality caveat. No filler or repeated schema details. Every sentence provides distinct value.

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

  Completeness4/5

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

  For a search tool with no output schema, the description explains the return fields and gives practical advice for selecting between data types. It does not cover pagination or default page_size, but the schema documents page_size constraints and data_types defaults. Overall it gives enough context to use the tool correctly.

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

  Parameters3/5

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

  Schema description coverage is 67%, with query and data_types documented. The description does not add extra meaning for any parameters beyond what the schema already provides. It mentions hasCoreMacros, which is a return field, not a parameter. Baseline 3 is appropriate since the schema covers most parameters.

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

  Purpose5/5

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

  The description states a specific verb+resource: 'Find foods by name in USDA FoodData Central.' It clearly differentiates from sibling tools like get_food (retrieval by id) and food_nutrition (nutrition facts) by focusing on searching by name and returning identifiers.

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

  Usage Guidelines2/5

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

  No explicit when-to-use or when-not-to-use guidance relative to siblings is provided. The description offers advice on preferring hasCoreMacros entries, but that relates to result interpretation, not tool selection. It does not mention alternatives such as get_food or food_nutrition.

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

• food_nutritionA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of disclosure. It explains key behavior: automatic best-match selection, nutrient scaling, and returning runner-up matches for correction. However, it does not mention how data_types affects the search or what happens on no match, but the core behavior is transparent.

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

  Conciseness5/5

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

  The description is three sentences: the first defines the core action, the second gives a concrete use case, and the third discloses a valuable feature. Every sentence earns its place, and the most important information is front-loaded.

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

  Completeness4/5

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

  Given no output schema, the description does a good job of explaining what is returned: nutrients scaled to grams and runner-up matches. It is reasonably complete for a simple lookup tool, though it omits details about the data_types parameter and ambiguity handling.

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

  Parameters3/5

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

  The description adds meaning to 'query' (search by name) and 'grams' (scaled to given grams), but the 'data_types' parameter is entirely unexplained. With schema coverage at only 33%, the description should compensate for all parameters, leaving one key filter without any semantic guidance.

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

  Purpose5/5

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

  The description clearly states the tool searches by name, picks the best match, and returns nutrients scaled to grams. It also distinguishes itself from siblings by emphasizing the one-step scaling feature, making the purpose 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.

  Usage Guidelines4/5

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

  It provides an explicit use case: "Use this for ordinary 'how much magnesium is in 30g of pumpkin seeds' questions." While it doesn't explicitly state when not to use it or name alternative sibling tools, the example strongly conveys the intended scenario.

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

• get_foodA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It explains the scaling behavior from per-100g basis, the %DV calculation against FDA values, and the inclusion of a citable source line. These are meaningful behavioral details that go beyond a simple 'get data' statement.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core purpose, and every phrase adds value: fdcId scoping, scaling, %DV, and source line. There is no redundant or generic wording.

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

  Completeness4/5

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

  For a simple two-parameter tool without an output schema, the description provides sufficient context: what it returns (full nutrient panel), how it behaves (scaling), and an extra output (source line). It does not cover error cases or return format, but these are less critical given the tool's simplicity and the description's clarity.

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

  Parameters4/5

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

  The schema documents 'grams' with a description and default, but leaves 'fdc_id' undocumented. The description clarifies that the tool targets 'one fdcId' and explains how grams are used ('scaled to the grams you ask for'), adding meaning to both parameters beyond the schema.

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

  Purpose5/5

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

  The description clearly states the verb 'get' and the resource: a full nutrient panel for a single fdcId, scaled from FDC's per-100g basis to requested grams with %DV. This specificity distinguishes it from siblings like search_foods and recipe_nutrition, and the focus on one fdcId separates it from a generic food_nutrition tool.

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

  Usage Guidelines4/5

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

  The description clearly implies when to use this tool: when you need nutrient data for a known fdcId, scaled to a serving size. It does not explicitly name alternatives or provide exclusion criteria, but the context is clear and the distinction from siblings is evident.

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

• recipe_nutritionA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries full responsibility for behavioral transparency. It clearly discloses the outputs: summed totals divided by servings, %DV, and per-ingredient contribution breakdown. It also explains how to handle off-database ingredients via manual_items. It does not cover failure modes or error handling for missing foods, but the main behaviors are well described.

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

  Conciseness5/5

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

  The description is two sentences—front-loaded with the main action, then a concise caveat about off-database items. Every phrase adds value, covering input, output, and special-case handling without unnecessary words. It is a model of efficient specification.

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

  Completeness4/5

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

  For a tool with no output schema, the description adequately communicates the return values (totals, %DV, per-ingredient breakdown) and the main input pattern. It addresses the special case of manual items. It does miss potential edge cases like what happens if a query matches no FDC entry and no manual_items is provided, but overall the description is complete enough for typical use.

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

  Parameters4/5

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

  The schema already documents servings and manual_items with descriptions, and the description adds semantic context for the items structure: {query or fdc_id, grams}. It clarifies the mutually exclusive lookup identifier choice and explains manual_items as ingredients with known nutrients. This enriches the 67% schema coverage, making the parameters clearer than the schema alone.

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

  Purpose5/5

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

  The description uses a specific verb ('Sum') and identifies the resource ('ingredient list'), clearly stating the core action: return per-serving nutrition. It distinguishes itself from siblings by emphasizing the recipe-level aggregation and per-ingredient breakdown, which contrasts with the likely single-item or lookup nature of get_food, search_foods, and food_nutrition.

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

  Usage Guidelines4/5

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

  The description makes the primary usage context explicit: supply an ingredient list with grams, get summed nutrition. It also provides guidance for a sub-case (ingredients not in FDC) by pointing to manual_items. While it does not explicitly name alternatives or exclusion criteria, the title and phrasing clearly separate it from the sibling tools, so the guidance is strong.

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