Unpublish an article

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

Adds substantial behavioral context beyond the annotations: the article returns to 'status: draft', the URL returns 404 after cache purge, changes content on the customer's site, and requires a specific secret key scope. This aligns with readOnlyHint=false and destructiveHint=false, and provides operational details that annotations do not disclose.

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 concise and front-loaded: it starts with the core action, then expands on the state change, external effects, and auth. Each of the five sentences adds distinct value, with no redundant or filler content.

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 tool with one parameter and no output schema, the description covers all necessary context: the action, the resulting draft state, the URL 404 behavior, the external site impact, the separation from publishing, and the required auth scope. It is complete for an agent to understand and invoke the tool 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?

The input schema describes the only parameter 'id' as 'A UUID', which is minimal. The description does not explicitly explain that 'id' is the article ID, though it is implied by the tool name and description. Since schema_description_coverage is 100% (the parameter has a description), the baseline is 3; the description adds no further parameter-specific semantics.

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 tool's function: 'Unpublish an article. Takes the article off the web and returns it to `status: draft`.' This uses a specific verb and resource, and explicitly distinguishes it from publishing ('Nothing becomes public: publishing is always a separate call') and deletion ('returns it to draft' implies not deleting). It is easily differentiated from sibling tools like publish_article and delete_article.

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 clear context for when to use the tool: to take an article off the web and revert it to draft. It also clarifies that making it public again is a separate call (publish_article). However, it does not explicitly contrast with delete_article for permanent removal, which would make the guidance more complete. The auth requirement ('Needs a secret key...') further guides usage.

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