merit_update_item

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

There are no annotations, so the description carries the behavioral burden. It usefully discloses that this is an update operation, that it targets an existing item by id, and that fields are patched rather than fully replaced. However, it does not mention potential side effects, authorization needs, response behavior, or idempotency, leaving meaningful 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 one compact sentence that front-loads the operation and endpoint, then immediately states the key constraint. There is no filler, repetition, or unnecessary detail.

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?

This is a mutation tool with no annotations and no output schema, and 7 of 8 parameters are undocumented. The description gives only the minimal call shape. An agent still lacks information about return values, error behavior, permissions, or the full semantics of the update, which is too incomplete for reliable invocation.

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 only 13%, with only id documented. The description adds that other fields are optional patches, which is helpful, but it does not explain the meaning or expected format of fields like taxId, itemGrCode, discountPct, or salesPrice. With such low schema coverage, the description should compensate much more than it does.

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 uses a specific verb ('Update') and resource ('Merit Aktiva item'), and includes the exact endpoint. This clearly distinguishes it from sibling tools like merit_create_items and merit_list_items, so an agent knows exactly what operation this tool performs.

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 clearly states that id is required and other fields are optional patches, which gives an agent clear instructions on how to call it. It does not explicitly name alternatives such as 'use merit_create_items to create new items', but the update semantics and id requirement provide enough context to avoid obvious misuse.

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