Add Weigh-In

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

The description discloses a critical behavioral nuance: that water, muscle, and bone percentages are accepted but discarded by Garmin on manual entry, and are only kept for smart-scale-uploaded measurements. This goes beyond the annotations (destructiveHint, openWorldHint) and provides essential information an agent needs to avoid surprising the user. It does not contradict 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?

The description is two sentences, front-loaded with the primary action and immediately following with a critical behavioral note. There is zero waste and the most important information appears first. It is perfectly sized for this simple tool.

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 simple add operation with complete schema and annotations, the description covers the action, the behavior of optional parameters, and implicitly the destructive nature (via annotation). It does not mention the return value or success response, but given there is no output schema and the operation is straightforward, this is not a critical gap. It is complete enough for an agent to call 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% with each parameter having a description, so the baseline is 3. The description adds value by explaining the real-world consequence of passing optional parameters (they are discarded), which the schema already hints at but the description reinforces with the manual vs. smart-scale distinction. This adds meaningful context beyond the schema, so a score of 4 is appropriate.

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 tool's purpose: 'Add a new weigh-in record.' It specifies the resource (weigh-in) and the action (add). It also mentions the stored fields and the discarded fields, which distinguishes this tool from related ones like get_weigh_ins and delete_weigh_in. The purpose is unambiguous and differentiates from siblings.

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 implies when to use this tool: when adding a manual weigh-in. It doesn't explicitly state alternatives or when not to use it, but the context (the sibling names and the explicit behavior about discarded fields) makes it clear. The note about Garmin discarding certain fields provides context about the tool's behavior but not about alternative tools. Given the simplicity and clear naming, this is adequate but not explicit.

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