Get Dri Lookup From Session

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

With no annotations, the description carries the full load and does disclose real behavior: the data source is session cache, population requires a prior store_dri_tables_in_session call, and only seven macronutrients are supported. It omits failure behavior when the session is unpopulated or an unsupported nutrient is passed, which is the main remaining gap for a read tool.

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?

Purpose and prerequisite are front-loaded and easy to scan, but the 'MATH TOOL INTEGRATION' block with three worked formula templates is disproportionate to this tool's job and reads as cross-tool advertising. Trimming it to one routing sentence ('use simple_math_calculator for adequacy/deficit/AMDR math') would preserve the guidance at a third of the length.

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 unnecessary, and everything else an agent needs — prerequisite, cached-data source, supported nutrient values, and when to apply it — is present. For a four-parameter read tool this is complete.

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 would be 3, but the description adds genuinely useful meaning: the 'Supported macronutrients' list effectively supplies an allowed-value set for the macronutrient parameter that the schema leaves as an unconstrained string. It adds nothing for session_id or age_range 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?

The first sentence gives a specific verb and resource ('Retrieve specific DRI values from session-cached data') and the caching angle implicitly separates it from the website-fetching siblings like get_specific_macronutrient_dri. It never names those siblings explicitly, so an agent must infer the split rather than being routed unambiguously.

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 states a hard prerequisite ('Must run store_dri_tables_in_session first') and gives a four-item 'Use this tool when' list covering lookup, recommendation building, comparison, and education use. It stops short of stating when NOT to use it — e.g. that a non-cached lookup should go to get_specific_macronutrient_dri — which leaves the main sibling ambiguity unresolved.

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