update_inventory

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It usefully discloses the 'partial update' behavior (only provided fields change) and that it targets an existing inventory by id, implying non-upsert semantics. However, it omits other relevant traits like response format, error cases, or required permissions, leaving significant gaps for a mutation 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?

The description is a single, front-loaded sentence with no redundant words. It conveys the verb, target, and key constraint (partial update) efficiently. Perfectly concise and well-structured.

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 the tool's simplicity (2 parameters, one flexible object), the description is minimally viable but not rich. It omits return value behavior and error semantics, which are left entirely unspecified with no output schema. The missing details are noticeable for a mutation tool, but the core update operation and partial-update behavior are present.

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%: both 'id' and 'data' are documented in the schema, including common fields for the data object. The tool description repeats the 'by id' concept but adds no further parameter-specific meaning beyond what the schema already states. Baseline of 3 is appropriate because the schema does the heavy lifting.

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 a specific verb ('Update'), the resource ('inventory'), and the scope ('by id', 'partial update'). This distinguishes it from retrieve/list/create/delete inventory tools as well as update tools for other resources in the sibling list.

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 gives no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing an existing id) or alternatives such as get_inventory for checking current state. The only hint is the operation itself, but no explicit use-case context or exclusions.

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