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

Beyond the annotation (readOnlyHint: false), the description discloses important behavioral traits: the link is public and anyone holding it can see the item, revoke=true removes an existing link, and the operation returns a URL. This gives the agent a clear picture of side effects and security implications without relying on an output schema.

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 three sentences, front-loaded with the core purpose, followed by a crucial privacy/side-effect note surfaces the security consequence, a concise revocation behavior, and the return value. Every sentence adds essential information with no fluff.

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 simple two-parameter tool with full schema coverage proxy, the description covers purpose, audience, side effects, revocation, and return value. No output schema exists, but the description explicitly states it returns the URL, so an agent has everything needed to invoke it correctly.

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 100%, so the schema already fully documents artifact_id and revoke. The description adds minimal new parameter meaning beyond restating the revoke behavior and the artifact_id source, so it does not meaningfully exceed the baseline.

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 states a specific action ('Put a generated item behind a public link') on a specific resource (generated item), and clarifies the intended use cases (posting, embedding, access by non-account holders). This clearly distinguishes it from siblings like get_artifact or read_artifact, which retrieve content rather than share 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?

The description gives clear context for when to use the tool: when a generated item needs to be publicly accessible via a link. It doesn't explicitly list alternatives or say when not to use it, but the use case is well-defined enough for an agent to select it appropriately among the many sibling tools.

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