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

Annotations only declare readOnlyHint and openWorldHint; the description adds genuinely supplemental behavior — live armory fetch, ~20k token budget, and the truncated_sections contract listing what was dropped and how to fetch it. It also discloses that talents return only the active spec's active loadout unless include_inactive_loadouts is set, and that raids/dungeons cover the current expansion newest-first, Mythic → Raid Finder.

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 purpose and defaults are front-loaded, and the dense clauses each carry information relevant to a 14-parameter tool. It is one undivided block, though, with section-by-section behavior compressed into run-on clauses that reward re-reading rather than skimming.

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?

For a large, no-output-schema read tool the description covers the return shapes section by section (gear, talents, M+, raids/dungeons, achievements, pets, quests) plus the truncation fallback, which is exactly what an agent needs before choosing sections. Nothing material about invoking it correctly is left unstated.

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 high (86%), so the baseline is 3; the description still adds real meaning beyond the schema, such as the per-item equipment shape (name, item level, track, stats, gems, enchants, bonus_list, set bonuses once in equipped_item_sets) and the {node_id, talent_id, name, rank} talent shape. Some parameter restatement (limit/offset paging, category selectors) duplicates what the schema already says, keeping it below a 5.

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 and resource plus data source ("Look up a live World of Warcraft character from Blizzard's armory") and enumerates exactly what is returned. It distinguishes itself from siblings by routing talent_loadout_code to decode_build, so an agent can tell it apart from get_talents and compare_character without opening the 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?

Gives concrete usage rules: default sections are equipment/talents/stats/mythic_plus, use achievement_category vs achievement_ids for different achievement needs, raid_expansions/dungeon_expansions for older content, statistics_category for stat values. It never states when to prefer a sibling like get_talents or compare_character, so it stops short of a full when/when-not/alternatives treatment.

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