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

Annotations only tell the agent this is a destructive non-read-only write; the description adds the important fallout semantics — the id and its attached ratings/eval results survive, the item KIND is immutable, and the call can return `needs_confirmation`. That is materially more than the annotation set provides and does not contradict it (the destructiveHint refers to overwriting the item's content in place).

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?

Three sentences, zero filler: the core action and its id-preservation consequence come first, the kind constraint and shape instruction second, the exclusions and confirmation caveat last. Each sentence carries information an agent needs before invoking.

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 destructive mutation with no output schema, the description covers the essential gotchas (immutable kind, preserved id/ratings, non-editable item types, possible confirmation response). It would be complete if it explained how the returned `needs_confirmation` maps onto the `approvalId` parameter, since that round-trip is otherwise left to inference.

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%, so the baseline is 3; the description still adds real meaning by constraining the `item` payload to the same three shapes returned by caliper_datasets_get and warning that the shape/kind cannot change. The `approvalId`/`needs_confirmation` connection is only hinted at rather than explained, keeping this short of a 5.

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 and resource ("Rewrites one item's content") and pins the scope to a single item within a dataset, which separates it from the dataset-level caliper_datasets_update and from caliper_datasets_add_items. It further clarifies the item retains its id, so an agent knows this is an in-place replacement rather than an add/remove.

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?

It gives clear prerequisites ("pass the same shape you read from caliper_datasets_get") and explicit exclusions ("Chat and raw items can't be edited from here"), plus the kind-preservation constraint. It stops short of naming the alternative tool for those excluded shapes or for replacing an item by delete+add, so it is clear context without full routing.

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