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

With annotations flagging destructiveHint=true and readOnlyHint=false, the description explains the destructive mechanism precisely: each call replaces the previously issued link, which then stops working even if an addition with it has started. It also discloses the 10-site cap, that no link is returned at the cap, and the ten-minute validity window — none of which the annotations convey.

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 core action is front-loaded and the important constraint — the 10-site cap and refusal behaviour — arrives early. The text is a bit baggy, repeating "adds one site" three times and packing the link-invalidation race condition into a single dense closing sentence.

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 no-argument tool with no output schema, the description covers everything an agent needs: what it returns, the failure condition, the link lifetime, and how a subsequent call invalidates the previous link. Nothing essential is left to inference.

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?

There are zero parameters, so the baseline is 4. The description explicitly confirms "Takes no arguments" and then enumerates the JSON fields returned (add_site_url, note, connected-site labels, site_limit), which preempts questions an agent might otherwise have about what to supply.

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 opening sentence names a specific verb and artifact: it returns a one-time link that adds one more site to this connection. It also clarifies what it does not do (no site is added until the link is used), which keeps it clearly separate from connect_status and the wp_* mutation tools.

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?

"Suited to connecting a further site; the sites already connected stay as they are" gives clear context for when to call it. It also states the hard precondition of at most 10 sites, at which point the call is refused. It never names an alternative tool or an explicit avoiding case, so it falls short of a 5.

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