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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds the context that it affects a 'public site' and is only for taking down a published design, which is useful. However, it doesn't disclose what happens to the design itself (e.g., whether it remains editable, whether the URL becomes inaccessible immediately) or any irreversibility beyond the annotation.

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 with no wasted words. The core action is front-loaded, and the usage condition is stated directly. Every word earns its place.

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 single-parameter tool with a clear name and sibling context, the description is nearly complete. The output schema exists, so return values are covered. The only gap is the lack of detail on the parameter's meaning, but the tool name and description make it obvious that job_id refers to the job whose design is being unpublished.

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 0%, so the description must compensate for the undocumented job_id parameter. The description mentions 'a job's public site,' which implies job_id identifies the job, but it doesn't explicitly explain that job_id is the identifier or provide any format details. With only one parameter and a clear name, the baseline is 3, and the description adds minimal but non-zero context.

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 clearly states the action ('Unpublish a job's public site') and the resource (a job's public site), distinguishing it from its sibling publish_design. It could be slightly more specific about what 'unpublish' entails (e.g., removing the site or making it private), but the verb and resource are 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 description provides a clear usage condition: 'Only when the user asks to take a published design down.' This tells the agent when to use the tool, and the sibling publish_design implies the alternative. It doesn't explicitly state when not to use it, but the condition is specific enough to guide selection.

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