Calorie MCP

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

Annotations already cover the safety profile (readOnly, non-destructive), so the description's job is to add behavior — and it does: accepted formats (JPEG/PNG/WebP), the returned structure (each detected food with weight and nutrition), and the operational gotcha that clients do not attach images automatically. It does not discuss failure modes for non-food or low-quality images, so not a 5.

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

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

Four short sentences, front-loaded with purpose, then format, then return shape, then usage condition. No filler and nothing repeated from annotations.

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

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

With no output schema and only two fully-documented parameters, the description fills the remaining gaps: accepted input formats, the return contents, and the explicit-passing requirement. An agent has everything needed 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it reinforces that the image must be passed explicitly as image_base64 and enumerates the supported formats beyond the raw enum-less string. That extra framing justifies a 4.

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 precise verb+resource ('Estimate calories and macros from a photo of food') and immediately distinguishes the tool from text-based siblings by noting the photo input. An agent can tell this apart from get_food_nutrition or search_foods without opening the schema.

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

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

Explicitly gives the selecting condition: 'Use when the user supplies a photo rather than naming a food,' which routes the agent correctly away from the name-based lookup siblings. It does not name a specific alternative tool or state exclusions (e.g., non-food images, multi-image), so it falls short of a 5.

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 destructiveHint=false, so the safety profile is covered. The description adds only a scope boundary (no food lookup); it does not disclose that this is a deterministic formula-based computation, the formula/population assumptions, or unit expectations beyond the schema.

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 short sentences, zero waste, with the core purpose front-loaded and the scope exclusion in second position. Nothing redundant or padded.

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?

An output schema exists, so return values need not be explained, and the annotations carry the safety profile. It is nearly complete for a pure-computation tool, though noting the underlying formula or applicability limits (e.g., adults only) would close the last 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 description coverage is 100%, so all six parameters are already documented with units and allowed values. The description's enumeration of inputs (age, sex, weight, height, activity, goal) merely restates the schema, and it even says 'sex' where the parameter is named 'gender'. Baseline 3 is correct.

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 ('Estimate') and resource ('daily calorie and macro targets'), plus the exact input dimensions used. The closing clause 'Does not look up foods' explicitly separates it from the food-lookup siblings like get_food_nutrition and search_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?

Provides a clear negative boundary ('Does not look up foods'), which tells the agent when not to use it, but no positive trigger such as 'use when planning a diet before logging meals' and no sibling alternative named. Clear context, missing explicit 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it returns calories and macros, but that is largely redundant with the existing output schema; no auth, rate-limit, or accuracy caveats are disclosed. Adequate given the annotation coverage, 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?

Two short sentences, front-loaded with the action and result, with the usage rule second. 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?

With an output schema documenting the return values and annotations covering the safe-read profile, the description needs only to state the transformation and the entry condition, which it does. Nothing essential is missing, though it could note how it differs from get_food_nutrition.

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 both parameters (grams, food_id) are already documented, including that food_id comes from search_foods. The description adds no syntax, unit, or range detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (scale), resource (one food), input basis (a gram weight), and output (calories and macros), so the agent knows exactly what it does. It doesn't explicitly contrast with the closer sibling get_food_nutrition, leaving the boundary to inference.

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?

"Use after search_foods when the user gives an amount" is a clear sequencing rule and trigger condition, which is genuinely useful. It stops short of an explicit exclusion (e.g. when to prefer get_food_nutrition), so it is clear context rather than full when/when-not 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 destructiveHint=false, so the safe read-only nature is covered. The description adds the useful behavioral fact that calculation requires search_foods-derived IDs and gram weights, but says nothing about failure behavior (e.g., unknown food_id) or which macros are returned beyond 'macros'.

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

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

Two tight sentences, front-loaded with what is computed and followed by the input requirement. No filler and nothing redundant.

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 need not explain return values, and it adequately covers purpose and inputs. It could be slightly more complete about invalid-ingredient handling or how servings affects per-serving output, but it is sufficient 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?

Schema description coverage is 100%, so the schema already documents grams, food_id, and servings. The description restates the food_id source and gram weighting and hints at per-serving output, but adds no syntax or constraint detail beyond the schema — baseline 3.

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: totals and per-serving calories/macros for a list of ingredients, which clearly separates it from get_food_nutrition (single food) and calculate_portion. It never explicitly names a sibling it is not, so it falls just short of full sibling differentiation.

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

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

It gives a concrete prerequisite workflow — 'Each ingredient needs a food_id from search_foods' — which tells the agent to call search_foods first. However, it offers no when-to-use vs calculate_portion or calculate_macro_targets guidance, so usage is only implied.

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 destructiveHint=false, so safety is covered externally. The description adds a genuinely useful behavioral trait beyond that: values are normalized per 100 g, which prevents misreading the returned panel as per-serving data. It omits auth needs, rate limits, and missing-food behavior.

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

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

Two short sentences, zero filler, and the core output contract (nutrient panel, per 100 g) is front-loaded before the input-sourcing hint. Nothing is redundant with the annotations or schema.

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?

An output schema exists, so return-shape explanation is not required, and the description still supplies the key unit convention plus the full input-acquisition path. Only edge cases (invalid food_id, missing data) are left unaddressed, which is acceptable for a single-parameter lookup.

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

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

Schema coverage is 100% and the schema already labels food_id as coming from search_foods, so baseline is 3. The description earns an extra point by widening the documented provenance to 'search_foods or lookup_barcode', adding meaning the schema alone does not convey.

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 ('Return the nutrient panel') with an explicit normalization basis ('per 100 g'), which tells the agent exactly what comes back. It names the sibling tools that supply the input (search_foods, lookup_barcode), which weakly differentiates it from the feeding lookups, but it does not contrast itself against calculation siblings like calculate_portion.

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 gives a clear prerequisite chain: obtain a food_id from search_foods or lookup_barcode, then call this tool. That is actionable context for when the tool is appropriate, though it stops short of any exclusions or a when-not-to-use clause.

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 destructiveHint=false, and the description is consistent with a safe read. It adds the per-100 g normalization of results, but says nothing about miss behavior (barcode not found) or external lookup/rate considerations, so value beyond the structured fields is modest.

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

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

Two tight sentences, zero filler: the action and return unit come first, the usage trigger second. Nothing could be removed without losing information.

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

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

With an output schema present, the description need not describe return values, and it correctly covers input type and usage trigger for a 1-parameter tool. The only gap is unstated failure behavior when a barcode resolves to no product.

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 "UPC or EAN digits, no spaces" constraint is already fully documented in the schema. The description's mention of "UPC or EAN" reinforces rather than extends that, so the baseline 3 applies.

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

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

States a specific verb (look up), a precise resource (UPC or EAN barcode), and even the return shape (macros per 100 g). This clearly separates it from name-based siblings like search_foods or get_food_nutrition, though it never names an alternative directly.

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?

"Use when the user provides a barcode number" gives a concrete triggering condition, which is strong for a single-input tool. It stops short of explicit exclusions (e.g., what to do when the user gives a food name instead), so it is clear context without routing against 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: the catalogue scale, the per-100 g normalization of results, and the chaining contract ('returns a food_id ... which calculate_portion and get_food_nutrition accept'). It omits match-failure behavior and any ranking/fuzzy-match semantics.

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, zero filler, with the highest-value fact (what it returns) and the routing instruction front-loaded. Every clause carries information the agent needs.

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 the safety profile, the description only needs to establish purpose, entry-point precedence, and the id handoff to downstream tools — all of which it does. Nothing required to invoke 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?

Schema description coverage is 100%, so the schema already documents query, limit, and verified_only including defaults and ranges. The description adds no parameter-level detail beyond confirming results are returned for a name query, so the baseline 3 applies.

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

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

States a specific verb and resource ('Search a catalogue of over 4 million foods by name') and the normalized return shape ('calories and macros per 100 g'). It also distinguishes itself from siblings by positioning itself as the entry point and naming the downstream consumers of its food_id 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?

'Use this first whenever the user names a food' gives explicit precedence over siblings like suggest_foods or get_food_nutrition, and names the two tools that accept its food_id. It stops short of stating when NOT to use it (e.g. barcode or photo inputs, which other siblings cover), so a small inference remains.

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 destructiveHint=false, so safety is covered. The description adds genuine behavioral context by narrowing the payload to 'food_id and name only', which tells the agent this cannot satisfy nutrition lookups and should be followed by get_food_nutrition — useful routing signal beyond structured data.

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 short sentences, zero filler, with purpose leading, usage condition second, and return scope last. Every sentence carries distinct information.

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

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

An output schema exists, so return values need not be re-explained, and annotations cover the safety profile. Purpose, trigger condition, and payload scope are all present for a simple two-parameter read tool — 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?

Schema description coverage is 100%, so both the limit and query parameters are already documented. The description restates 'partial food name' but adds no syntax, format, or matching-behavior detail beyond the schema — baseline 3 applies.

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

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

States a specific verb+resource: 'Typeahead suggestions for a partial food name.' The 'partial/incomplete' framing implicitly distinguishes it from search_foods, but no sibling is named explicitly, so full differentiation relies on the agent inferring the contrast.

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?

'Use when the name is incomplete' gives a clear triggering condition, which is strong context for a suggestion endpoint. It stops short of explicitly naming search_foods as the alternative for complete names or full-text queries, so the routing rule is implied rather than stated.

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