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

Annotations already flag destructive=true and openWorldHint=true, so the bar is lower; the description still adds real context by explaining that 'link' makes the artifact readable by anyone with the URL and that 'public' additionally makes it 'listed'. That exposure/consequence detail is exactly what annotations cannot convey.

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?

Two sentences, no padding, and the operation is front-loaded before the visibility options. The compressed, fragmentary style ('beyond its home', 'link: internal editors') costs some readability but wastes no words.

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?

An output schema exists, so explaining return values is optional (the URL mention is a bonus), and annotations cover the safety profile. However, for a destructive sharing change the description omits the conflict-guard parameter and gives no hint about reversibility or permission requirements.

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 only lightly supplements: it says 'link ... needs no why' (partially restating the schema's note) and 'returns the URL', but says nothing about expectedWorkspaceRevision or how CONFLICT is surfaced.

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 and resource ('Set who beyond its home can read an artifact') and enumerates the three resulting states. An agent can tell this is a sharing/visibility mutation, though the boundary versus sibling artifact_publish is not drawn.

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?

Gives conditional guidance embedded in fragments ('standalone only: listed', 'A workspace artifact takes private or link'), which is useful but telegraphic. It never states when to prefer this over artifact_publish or artifact_update, and the 'internal editors' phrase is left unexplained.

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