Archive Inventory Item

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

Annotations already indicate readOnlyHint=false and destructiveHint=true, so the description correctly aligns with a mutating, destructive-intent operation. The description adds important context: the operation is non-destructive in terms of data loss ('archive instead of destructive delete'), there is a $0.10 monetary cost, and an API key is required. Ironically, the annotation destructiveHint=true may mean the operation is considered destructive (e.g., it removes the item from active lists), but the description clarifies it is not a permanent delete. The description adds value beyond annotations by disclosing cost and authentication requirements.

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 extremely concise: one sentence with three useful clauses: the operation type, the cost, and the auth requirement. It front-loads the most important behavioral distinction ('Archive instead of destructive delete'). It could be slightly more structured (e.g., separate cost and auth into a second sentence), but it earns every word and has no wasted content.

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 tool with an output schema, 4 parameters, and destructiveHint=true, the description is minimally adequate: it tells the agent this is an archival operation with cost and auth requirements. But it doesn't explain the meaning of reason, what happens to the archived item (e.g., is it still visible in get_inventory?), or how retries work with idempotency keys (though the schema documents retries). Given the output schema exists, return values don't need explanation, but the behavioral consequence of archiving is left partially inferred.

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 50%, with documented parameters being request_id and idempotency_key. The description does not explain inventory_id or reason beyond the schema's basic type declarations. However, the description's 'Archive instead of destructive delete' implies inventory_id is the target item, and reason is presumably an audit/archive reason. Baseline 3 is appropriate because the schema covers half the parameters and the description partially compensates by clarifying the operation's nature, but it doesn't add specific meaning to the undocumented parameters.

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 'Archive instead of destructive delete' which clearly indicates the operation is a non-destructive archival action on an inventory item. It distinguishes itself from delete operations by emphasizing it is not destructive, though it doesn't name a specific sibling alternative like delete_event or delete_food. The related get_inventory_item, update_inventory_item, and add_inventory_item siblings help contextualize it, but the primary behavior (archive an inventory item) is clear.

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 'instead of destructive delete' phrase provides an implicit usage guideline: use this when you want to remove an inventory item from active use without permanently destroying it. However, it does not explicitly state when to use this over update_inventory_item (e.g., when the item should be retired) or contrast with alternative archive tools like archive_asset, nor does it mention the $0.10 cost as a decision factor. This is adequate but relies on inference.

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