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

Annotations already mark it non-read-only, non-idempotent, non-destructive, and open-world. The description adds important behavioral context beyond annotations: it creates only a draft, nothing on Google changes, certain links are refused, and the returned draft must be shown to the owner before publishing.

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?

Five tight sentences. The purpose is front-loaded, followed by restrictions, the draft-only guarantee, and the required publish workflow. Every sentence adds useful information with no repetition or filler.

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?

Given no output schema, the description still tells the agent that a draft is returned, that it must be shown word for word, and that publish_change is the correct follow-up only after approval. This is complete for a draft-proposal tool with sibling publishing/discarding tools.

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 67%, with url and link_id described and action supplied as an enum. The description adds meaningful constraints for the url parameter by refusing social media/Google links and provider-set links, but it does not explain action or link_id beyond what the schema provides.

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: draft a change to the link behind the listing's Book button. It distinguishes the draft action from the later publish step by saying 'Creates a DRAFT only', so the agent can tell it apart from publish_change.

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?

Explicitly gives when-not conditions: links set by a booking provider cannot be changed here, and social media/Google links are refused. It also names the alternative publish_change and the condition for using it: only after the owner says yes.

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