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

Goes well past the annotations: delete is soft (30 days in trash, returns dates), workspace items require a why, per-item revision entries cause CONFLICT refusal on changed items, and the tool returns all 'safe' failure IDs and counts without retrying destructive failures. That partial-failure model is exactly the behavioral context an agent needs before firing a destructive batch and is nowhere in the structured fields.

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?

Front-loaded with the verb and scope, then the per-action constraints, then failure semantics — no filler sentences. It is telegraphic to the point of being slightly cryptic ('safe failure ID and count' is never unpacked), which costs a point.

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?

Destructive profile, per-action requirements, conflict behavior and partial-failure reporting are all covered, and an output schema exists so return shape needn't be restated. Minor gaps remain, such as whether a batch may span multiple workspaces/teams, which matters for a 200-item operation.

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 83%, so the schema already documents most params; the description still adds value by spelling out the folder resolution precedence (artifacts' workspace, else team, else personal), the meaning of folder: null, and that move's folder/team are ignored on delete. The dependency between action and which params are legal is genuinely extra information.

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?

States a specific verb pair and resource with scope: 'Apply move or delete independently to at most 200 artifacts.' The batch limit plus the fact that it takes artifactIds makes it unambiguous that this is the bulk counterpart to artifact_move/artifact_delete, and the first sentence alone is enough to choose it.

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?

Explains the decision between the two actions: move requires a folder (or null to unfile), delete takes no folder or team and parks each item in trash for 30 days. It doesn't explicitly name artifact_move/artifact_delete as the single-item alternatives, so the batch-vs-single routing is implied by 'in bulk' rather than stated.

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