Bulk Get Cnf Macronutrients

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

With no annotations, the description carries the full burden, and it does disclose the 20-code cap, the continue_on_error default, and that ingredient linking happens 'in one operation' instead of a separate step. However, the side effect of writing data into a session (via session_id) is only hinted at and it never says whether existing session data is overwritten, what happens with more than 20 codes, or what failure entries look like.

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?

Roughly 200 words of largely promotional framing — 'massive efficiency gains', 'streamlined', 'enables immediate nutrition calculations' — restate the same bulk-efficiency benefit three times. The 13-nutrient list and the Returns paragraph duplicate structured data (nutrient scope and output schema), so much of the text does not earn 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 nested-object tool with an output schema and 100% schema coverage, the description covers inputs, the linking pathway, and error-continuation behavior well. The remaining gap is session-state semantics — what gets stored and whether repeated calls accumulate or replace — which matters for a tool keyed on session_id.

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 each nested field is already documented, including defaults and the recipe_id/ingredient_mappings dependency. The description restates the same fields ('food_code to ingredient_id mapping', 'required for automatic ingredient linking') without adding format or constraint detail beyond the schema, so 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?

The description states a specific verb+resource ('retrieves core macronutrient data for up to 20 food codes' from the Canadian Nutrient File) and scopes it as the bulk counterpart to single-code fetching. It never names the sibling 'get_cnf_macronutrients_only' or 'search_and_get_cnf_macronutrients', so the agent must infer the split from the phrase 'bulk processing' rather than an explicit 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?

A dedicated 'Use this tool for:' block gives four concrete scenarios (multi-ingredient recipe analysis, bulk processing of known codes, known ingredient-CNF relationships, large-scale prep). What's missing is an exclusion rule — nothing says to use the single-code sibling for one-off lookups or to use search-and-get when codes are unknown.

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