measurements_update_bmi

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

With no annotations, the description carries the behavioral burden. It discloses the partial-update behavior ('Only provided fields are changed') and implies the target record must exist. It does not address error behavior for invalid IDs, permissions, or side effects beyond the mutation, though output is covered by an output schema.

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 short sentences carry all essential information, with the action front-loaded. There is no filler or redundancy; both sentences contribute meaning.

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 4-parameter tool with a required ID, no annotations, and an output schema present, the description covers core semantics but omits failure behavior (e.g., what happens if bmi_id is invalid) and does not reference sibling tools. The input and output schemas handle parameter and return-value details, so the gaps are moderate.

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 every parameter is already documented. The description adds a global semantic about optional parameters: 'Only provided fields are changed' clarifies that supply is what triggers an update, which is not stated in individual parameter descriptions. It does not add per-parameter details 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 description clearly states the action and resource: 'Update an existing BMI record' uses a specific verb and resource, and 'Only provided fields are changed' further distinguishes it from create/delete siblings. The resource 'BMI' separates it from other measurement update tools like height or weight updates.

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 usage: 'existing' suggests updating rather than creating, and 'only provided fields are changed' gives partial-update semantics. However, it never explicitly names alternatives such as measurements_create_bmi or measurements_delete_bmi, nor provides exclusion criteria. The guidance is implied rather than explicit.

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