Coda Unpublish Doc

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds real side-effect detail: public access is removed, the public URL stops working, the action is reversible, and a doc_id confirmation is returned. That is exactly the context annotations cannot express.

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 action and its effect in the first clause, then reversibility. Slight redundancy between 'removing public access' and 'The public URL will stop working', but each sentence still carries usable information.

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 mutation with annotations covering the safety profile and an output schema covering the response, the description supplies everything else an agent needs: the state transition, the user-visible consequence, and reversibility.

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?

One parameter with 100% schema description coverage, so the schema fully documents doc_id; the description adds no format or sourcing guidance for it. The note that confirmation includes doc_id concerns output rather than input semantics, so the baseline 3 holds.

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 ('Unpublish') and resource ('a Coda doc') plus the concrete effect ('removing public access'), which is more than a restatement of the name. The mention of coda_publish_doc as its inverse cleanly separates it from the nearest sibling.

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 clear context: use it to revert a previously published doc to private, and points at coda_publish_doc as the reverse operation. It stops short of an explicit 'when not to use this' (e.g. permission prerequisites or cases where sharing should be changed via coda_get_sharing_metadata / permission tools instead).

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