log_custom_food

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

Despite no annotations, the description clearly indicates a write operation ('log') and adds context that values are 'per serving', which is crucial for interpreting the nutrition parameters. It could mention that entries are added to the diary, but the verb 'log' strongly implies this. No contradictions with annotations.

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 concise sentences achieve everything: definition, usage guidance, and per-serving note. No fluff or redundancy. Perfectly front-loaded with essential 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?

Given 15 parameters, 100% schema coverage, and an output schema (not shown but present), the description covers core behavior, usage scenarios, and per-serving semantics. It does not detail the output format, but the output schema handles that. Slightly lacking mention of the diary context (e.g., 'logs to the user's diary'), but the meal and date parameters imply it.

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 is 3. The description adds value by clarifying that all nutrition values are per serving, which directly impacts how the `servings` parameter is used. This extra context goes beyond the individual parameter descriptions.

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 'log' and resource 'custom food', and differentiates from sibling tools like search_food by explicitly noting 'without needing a match in the food database'. It also lists specific use cases (restaurant meals, homemade dishes), making the purpose unmistakable.

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 guidance on when to use this tool: 'Use this for restaurant meals, homemade dishes, or anything where you know the calories and macros but search_food has no good match.' This clearly separates it from alternatives and implies not to use it when a database match is available.

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