Request connections

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

Annotations only declare the generic flags (readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false). The description adds the operationally critical, non-obvious behavior: the call does not actually establish a connection, the user must complete it out-of-band, secrets must never be requested in chat, and the result must be resolved by polling check_setup. That is real disclosure the annotations cannot carry.

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, then the sourcing rule, the hard constraint, and the follow-up loop — every sentence is operational. The trailing 'Returns sessionId, connectUrl and expiresAt' duplicates what the output schema already declares and is the one sentence that does not fully earn its place.

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 a two-parameter tool with a full output schema and annotations, the description covers the only things an agent could still get wrong: which provider ids to pass, that it cannot complete the connection itself, the anti-pattern of asking for secrets, and how to detect completion. Nothing material is missing.

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 the parameter definitions already carry the basics (provider id array, optional workflowId). The description still adds value by telling the agent where to source the provider ids and the conditional 'cloudflare' case; it says nothing extra about workflowId, which is the only remaining gap.

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 ('Create one short link the user opens to connect the services you name, with one button per service') that an agent can immediately distinguish from siblings like check_setup or verify_connection. The mechanism (one link, one button per service) is concrete rather than abstract.

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 says where the provider ids come from ('Use the ids from check_setup's missingProviders, plus cloudflare if it is not connected'), states the constraint ('You cannot create a connection yourself'), forbids the wrong alternative ('must never ask the user to paste a secret into the chat'), and prescribes the follow-up loop ('poll check_setup with the returned sessionId ... until connectionRequest.complete is true'). When, when-not, and the alternative are all named.

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