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

With destructiveHint already declared, the description still earns credit by specifying exactly what is destroyed and what survives: '`delete` with `confirm: true` removes the project, its order and its share list permanently; its artifacts stay.' It also discloses the non-obvious confirm requirements (adding a private artifact to a shared project, widening one holding private ones). The gap is the read path — 'or read it' gives no indication of what is returned, and there is no output schema to fill that in.

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 resource definition, then mode-selected behavior, then a disambiguation note; almost no filler. Some phrasing is compressed to the point of being terse ('else list yours', 'a `rule` adds matches as they are published'), which costs a little parseability but no words are wasted.

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 13-parameter, polymorphic create/read/update/delete tool with no output schema, the description covers mode routing, deletion semantics, and confirm rules well. The remaining gap is the read/list path — an agent knows how to ask but not what shape of project, item list or ordering comes back.

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 92%, so the baseline is 3; the description goes beyond it by mapping parameters to operations (title renames, order/move reorder, rule auto-adds matches as published) and by explaining the cross-parameter dependency on `confirm`. It does not explain `groupLabel`/`collapsedGroups` or `workspace` scoping, but the schema covers those.

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 opens by defining the resource concretely (an ordered set of artifacts shown one at a time at /s/{slug}, with its own audience and share list) and then enumerates the operations: create, list, add/remove, rename, set visibility, reorder, rule, read, delete. It explicitly disambiguates from the sibling case ('An artifact's gallery label is not a project: that is `collection` on super_artifact_set'), which is exactly the kind of routing an agent needs.

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?

Mode selection is stated as a condition on arguments: no `project` + `title` creates, no `project` without `title` lists yours, `project` present switches to mutation or read. It also names the alternative tool (`super_artifact_set` with `collection`) for the confusable case, and constrains batching ('One change per call, or title with visibility').

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