set_nutrient_target

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true. The description complements this by explaining that only passed parameters change, other settings are preserved, and that setting visible toggles tracking. It also warns that overwriting a target should be preceded by a get_targets call because the change may need manual reversal. This adds meaningful behavioral context beyond the annotations, though it doesn't detail the output behavior; with a rich output schema present, that is acceptable.

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?

The description is well-structured and front-loaded. The first sentence states the core action, followed by short paragraphs explaining custom targets, partial-update behavior, and recovery guidance. Args are cleanly listed at the end. Every sentence earns its place, and the length is proportionate to the tool's complexity.

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 mutation tool with one required parameter, three optional parameters, and an open-world hint, the description covers the essential behavioral context: what changes, what doesn't, how to discover valid nutrient names, and how to avoid data loss. The presence of an output schema means return-value details need not be in the description. It is complete enough for an agent to call this tool correctly without guessing.

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 0%, so the description carries the full burden for parameter meaning. It explains nutrient (with examples and list_nutrients reference), minimum/maximum (daily target and upper limit in the nutrient's own unit), and visible (tracking toggle). It also clarifies the semantics of omitting parameters: only what you pass changes. The only minor gap is the unit ambiguity for minimum/maximum, but it is addressed with "in that nutrient's own unit."

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 opens with a precise verb+object: "Set a nutrient's daily target, its upper limit, or whether it is tracked." It clearly identifies three distinct actions and names the resource (nutrient). This distinguishes it from siblings like get_targets (read) and list_nutrients (listing).

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 explicitly explains when to use this tool: to set custom targets, toggle tracking visibility, and how it interacts with defaults. It also routes the agent to get_targets for reading current values before overwriting, and notes that reverting to defaults is done in the app, not via this tool. This is clear when-to-use and when-not-to-use guidance.

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