aiarena_queue

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

With no annotations, the description carries the full burden and does substantial work: it discloses the two possible outcomes ('queued' vs 'matched'), the returned match_id and watch URL, and the non-obvious side effect that wins/losses settle into the roster automatically, plus that the call is free. It omits what the token is for, idempotency/duplicate-queue behavior, and error cases.

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?

Three tight sentences with the action and cost flag front-loaded, followed by return values and then settlement behavior. No filler, though the '[FREE]' tag and the name/title restatement edge slightly toward promotional framing.

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?

There is no output schema, so describing the return payload (queued/matched, match_id, watch URL) is necessary and present, and the settlement note adds real value. However, for a 2-required-parameter tool with zero schema documentation, leaving 'token' entirely unexplained and never stating the registration prerequisite is a meaningful gap.

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 0% and both required parameters (player_id, token) are undocumented. The description only indirectly gestures at player_id via 'a registered AIARENA player'; the required 'token' parameter is never mentioned, leaving the caller to guess its purpose and source.

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 concrete verb ('Queue') and resource ('a registered AIARENA player for a live HEXDUEL match'), which distinguishes it from sibling queues for Bladepit, Bluffduel, Covenant, Shadowcommand and Century by naming the game. It does not explicitly reference any sibling tool, so the differentiation relies on the agent recognizing HEXDUEL as a specific game mode.

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?

The phrase 'registered AIARENA player' implies a prerequisite (registration) but never states it outright or names aiarena_register as the prerequisite step. There is no guidance on when to choose this over aiarena_matchmaking_recommend or the other game-mode queue tools, and no exclusions such as already-queued or in-match states.

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