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

Annotations already declare destructiveHint=true and non-idempotent, and the description usefully adds the auth requirement (api_key from register_agent), the paper-only constraint, the premium purchase precondition, and the auto-slot-assignment behavior. It does not explain what the destructive hint means in practice (e.g. whether an occupied slot's skill is replaced), which is the one thing an agent would most want to know.

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?

Dense but front-loaded: auth, action, scope, slot behavior, prerequisite, related tool, REST twin. Parenthetical asides ('register_agent, no key needed', 'paper or live, X-API-Key accepted') are slightly cluttered but each carries information.

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 4-param mutation tool with no output schema, the description covers auth, scope, prerequisites, slot behavior, the loadout-inspection sibling and the REST equivalent. The remaining gap is the consequence of the destructive write itself, which the annotations flag but the description never resolves.

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 all four parameters are already documented in the schema. The only parameter fact in the description — 'auto-assigns a slot when slot_position is omitted' — is already stated verbatim in the slot_position schema description, so it adds no new meaning.

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+resource ('Equip a skill') and immediately narrows the scope to 'one of YOUR PAPER clones', distinguishing it from live-mode siblings. It also names get_bot_skills as the read-side counterpart, so an agent can place it without opening a 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 a real prerequisite ('Premium skills must be bought first') and points at get_bot_skills for inspecting the current loadout. It does not, however, contrast with the sibling equip_bot_model or say when equipping is the wrong move, so it stops short of full routing guidance.

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