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

The description adds meaningful context beyond the annotations: the write is confined to the caller's own record, it is undoable from the same surface, and it returns an ordinary result rather than a plan_token. But it never explains what the destructiveHint=true actually risks (e.g. whether an archived item loses visibility or triggers downstream routing), and the internal jargon 'plan_token' is unexplained.

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 core behavior and the allowed values are front-loaded in the first sentence, and the confirmation note follows. The second half drifts into platform-wide policy ('Everything destructive, outbound or financial still proposes and waits'), which is broader than this tool needs.

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 two-parameter, no-output-schema tool, the description covers purpose, ownership scope, allowed values and confirmation behavior. The remaining gaps — id format and error/edge behavior — are modest but real for a mutation tool.

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 0%, so the description must carry parameter meaning. It clarifies that inbox_id identifies the caller's own item and restates the three status values already present in the enum, but gives no hint about accepted id formats (the schema permits both integer and string) or what happens with an unknown id.

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 opening sentence names a specific verb and resource ('Set the status of one of the caller's inbox items by id') and enumerates the allowed values (pending/routed/archived). The ownership constraint ('Only the caller's own item is reachable') further pins down scope, which clearly separates it from siblings like delete_inbox_item or route_inbox_item.

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 CONFIRMATION block states explicitly when this tool fires without a proposal ('runs immediately when the caller asks for it') and contrasts that with what still 'proposes and waits.' That is real routing guidance, though it never names a sibling alternative such as route_inbox_item for the routed transition.

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