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

Annotations only declare destructiveHint=true and readOnlyHint=false, but the description explains that nothing is copied by the call itself, that the agent cannot confirm it, that the member must tap Confirm in Studio, and that the link is single-use, account-bound, and expires in 10 minutes. This resolves the apparent tension between the safe mint step and the destructive downstream action the flagged annotations imply.

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?

Four compact sentences, front-loaded with what the tool does and when to use it, then the behavioral constraints. Every sentence carries distinct, non-redundant information, including the return shape.

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?

With no output schema available, the description compensates by naming the return payload ({url, expiresAt}), plus the lifetime, single-use, account-scope, and both-workspaces-ownership constraints. For a tool whose execution defers a real mutation to the member, this covers everything an agent needs to call and then handle the result.

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 description coverage is 100%, so connectionId, toProject, instanceName and the mode enum are already documented in the schema. The description restates the copy-vs-move semantics that the mode enum encodes ('copies (or moves)') but adds no format, default, or validation detail beyond it, so the baseline of 3 applies.

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 ('Mint a one-tap link that copies (or moves) one connected service from one of the member's workspaces into another') and frames the fallback relationship to the sibling connections_copy_connection via the cross_workspace_refused condition. An agent can distinguish this from connections_copy_connection and the other connections_* tools without opening either 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 an explicit trigger ('for when the member asked you to do it and connections_copy_connection returns cross_workspace_refused') and a precondition ('Both workspaces must be the member's own'). It names the alternative tool and the exact condition that routes to this one, leaving nothing to inference.

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