Create a relay session (host-client games only)

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

Annotations cover openWorld/idempotent/destructive, but the description adds substantial context beyond them: the host-risk profile (host can cheat, has a latency advantage, host's PC caps the match, match ends if host quits), that the call blocks until ready, what is returned (relay address plus per-player authorization tokens), and that sessions are billed while open with a cleanup path via edgegap_delete_relay_session.

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 warnings are front-loaded and every sentence carries real decision weight for a high-stakes, billable, non-default tool. It is long and slightly repetitive about the host's role and the 'no server image' caution, but not padded in a way that harms comprehension.

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, the description still explains the return payload (relay address and per-player authorization tokens), the blocking behavior, billing implications, and the deletion follow-up. Nothing an agent needs to call and then manage this tool correctly 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 description coverage is 100%, so baseline is 3. The description reinforces the host-first ordering of user_ips and points to edgegap_authorize_relay_user for late joiners, but these details already live in the schema, so it adds little beyond it.

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 description states a specific verb and resource ('Creates an Edgegap relay session') and explicitly contrasts it with the sibling edgegap_deploy by declaring 'A relay is NOT a game server'. An agent can distinguish this tool from deployment tools 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?

It gives explicit when-to-use ('Only use this when the developer has chosen peer-to-peer/host-client, or the netcode is already a listen server'), when-not ('for a multiplayer match, deploy an authoritative dedicated server with edgegap_deploy instead'), a routing instruction to ask first if that hasn't been established, and an explicit anti-pattern ('Never pick it only because it needs no server image'). This is a complete routing guide.

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