Change a player

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so safety is partly covered. The description adds real value with the online precondition and the exact `player_offline` error token, but omits side effects an agent would want — e.g. whether health=0 kills the player, whether the change is transient, and whether unspecified properties are left untouched.

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?

Two sentences, zero preamble: the property enumeration comes first and the hard precondition second. The comma-spliced property list is dense but each clause adds information; nothing is filler.

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 18 parameters, no output schema, and sparse schema descriptions, the description gets most of the way there but leaves meaningful holes: an omitted parameter, no statement of what a successful call returns or confirms, and no note that supplying only `player` produces no change.

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 only 17%, so the description must carry the load. It partly does: it names nearly every settable property and supplies ranges and defaults for food (0–20) and speeds (-1 to 1; 0.2/0.1). But it leaves out `exhaustion` entirely, never distinguishes `level` from `exp`, and gives no units for health, fireTicks, or remainingAir.

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?

Opens with a specific verb ('Set') and enumerates the exact player properties affected, so the resource and operation are unambiguous. It doesn't name or contrast any sibling, but 'player' plus the Minecraft-specific property list inherently separates it from update_entity, set_effects, and teleport_player.

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 only usage rule given is the precondition 'The player must be online; otherwise the error is `player_offline`', which is genuinely useful. There is no guidance on when to prefer this over siblings such as update_entity or set_effects, and no statement that at least one property should be supplied (only `player` is required, so a name-only call appears legal but pointless).

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