Player

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

Annotations already declare read-only, idempotent, non-destructive, but the description adds genuinely new behavioral facts: offline players return stale last-known location, offline inventories come from the saved player file, several parts require the players:private permission, and permission checks answer whether the player is an operator. It even flags that item names, lore, and book titles are player-written data rather than instructions, a prompt-injection caveat nothing in the structured fields conveys.

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?

Long, but almost every clause maps to a distinct behavioral fact, and the highest-value information (what is returned, offline vs online, permission gate) is front-loaded. It is one dense paragraph with heavy nested parentheses, so scanning for a specific `include` value is harder than it needs to be; light structure would have earned a 5.

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 the description carries the full return-value burden, and it does: it describes item payloads (enchantments, attributes with tooltip adjustment, potion durations in ticks, armor trim, shulker/bundle contents) and notes that inapplicable fields are omitted. For a six-parameter read tool with permission-gated sections, nothing an agent needs to call it 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 coverage is already 83%, so a 3 would be the floor, but the description goes well beyond it: each `include` value is explained with its return shape and online/offline constraint, `statistics` categories are spelled out with units (play_time in ticks, distances in centimeters), and `permission` is illustrated with a concrete node such as worldedit.wand. The inventory slot map (0–8 hotbar, 36–39 armor, 40 offhand) and ender chest 0–26 add interpretation the schema lacks.

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 (a player's profile and, while online, full state) and then enumerates the exact state fields returned: game mode, health, food, XP, location, flight, speed, ping, client. It also distinguishes the single-player case from the batch case via `players` (up to 10) and from optional payloads via `include`, so an agent can tell it apart from siblings like list_players or get_entity_summary.

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 strong conditional guidance on the optional parts: `effects` and `target` are online-only, `inventory`/`enderchest` come from the saved file while offline, `statistics` is all-or-one-category, `advancements` has todo/done/all semantics. What it never does is name an alternative tool or state when to prefer list_players or get_entity_summary instead, so the when-not side is implicit.

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