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

Annotations only say non-read-only, idempotent, non-destructive; the description adds substantive behavior beyond that: the site keeps its address and its sharing, and re-pointing signs out everyone currently signed in and reopens the app. That session-invalidation side effect is exactly the kind of consequence an agent cannot infer from the schema or hints.

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 core action and the id source, then the preserved-state payoff, then the side effect, then the sibling redirect — a sensible ordering. It is dense but slightly overlong; the final sentence on open_url routing is useful yet takes space to make a point that could be tighter.

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 mutation tool with annotations and no output schema, it covers purpose, prerequisites, preservation effects, session consequences, and when to use a sibling. The only gap is what the call itself returns — it notes web_link_create returns an open_url but never says whether the update returns the site, which matters since no output schema exists.

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 100%, so baseline is 3; the description adds real meaning on top by framing name vs target as two distinct edit modes and stating that target is 'as seen from the server, a start page may follow'. It adds little about https_inside beyond the schema, which already says the site itself speaks https.

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?

Opens with a specific verb+resource: change one of the internal sites in the owner's cabinet by id, then enumerates the exact mutations (rename, re-point at another host:port or start page). It explicitly distinguishes itself from web_link_delete ('instead of removing it and adding a new one') and from web_link_create, so an agent can place it among siblings without opening any schema.

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 both a when-to-use ('the app moved') and a when-not-to-use with a named alternative ('To send the user to another page of the same app, don't change the site: call web_link_create'). It also tells the agent that id comes from web_link_list or web_link_create, closing the discovery loop.

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