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

Beyond the destructiveHint/idempotentHint annotations, it discloses the concrete blast radius (all historical messages and pinned items hidden plus a broadcast), what is NOT destroyed (no account ban, other sessions untouched), field-level return semantics (hidden = true total, notified = broadcast count only, possibly capped at ~200), idempotency behavior (repeat keeps muted), and a retry-safety warning for unknown results. This is unusually rich behavioral context that goes well past what the annotations convey.

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 single dense sentence is front-loaded with the gating requirement (login + organizer role) and packs requirement, scope, side effects, return meanings, and retry policy without filler. It is information-dense to the point of being slightly crowded, but no clause is wasted.

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 no output schema, the description proactively explains the return counts (hidden vs notified) and their caveats, and it covers auth, scope boundaries, side effects, idempotency, and retry safety. An agent has everything needed to call this destructive tool correctly.

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 100%, so the baseline is 3. The description adds operational meaning on top of the schema: it instructs verifying targetUserId against the actual person at the host desk and confirming activity/session/scope, which sharpens how activityRef and liveId scoping should be applied in a destructive action.

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?

The description states a specific verb and resource (ban this user for the current live session) and immediately scopes it: mutes danmaku questions and hides all of the user's historical messages and pins in this session, with broadcast. It also rules out confusion with account-level bans, explicitly noting it does not ban the account or affect other sessions, distinguishing it from siblings like block_user or unban_live_user.

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?

It gives a clear precondition (login required, must be this session's organizer, verify targetUserId at the host desk) and explicit when-not guidance (do not arbitrarily batch, does not affect other sessions). It stops short of naming alternative sibling tools to use instead, so it is strong context without full alternative routing.

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