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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds substantial behavior beyond those: login requirement, the audience-gate (not signup) rule, that hidden/mutual-block messages are excluded (so results are not 'full'), pagination semantics (default 1000/max 2000, reachingLimit flag, nextSinceOffsetMs continuation), and the deliberate absence of a send capability. This is exactly the kind of non-obvious behavior an agent needs.

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 description is dense and longer than average, but every section earns its place: 何时用 (purpose), 组合链 (chain), 口径/坑 (numbered pitfalls). Information is front-loaded with purpose before details, and numbered bullets aid scanning. The length is justified given the number of non-obvious pitfalls (pagination, access gate, data completeness), though it could be slightly trimmed.

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 must carry the return-format burden. It covers login, access gates, data-completeness caveats, ordering, pagination, and read-only nature, and hints at the response shape via reachingLimit and nextSinceOffsetMs. The return object's fields are not fully enumerated, which is the main gap for a tool this complex.

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 100%, so the baseline is 3. The description adds value beyond the schema: kind=QUESTION filters and sorts by offsetMs ascending, liveId provenance (from get_organizer_live), and sinceOffsetMs used for pagination continuation. It reinforces limit's default/max and ties it to the reachingLimit/nextSinceOffsetMs behavior, enriching the bare schema entries.

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 opens with a concrete use case ('把这场的观众提问整理成纪要 / 看大家在哪一分钟最热闹'), states the verb and resource (export live interaction timeline), and clarifies that kind=QUESTION yields an ordered, analyzable time series. It names its position in a composition chain (list_my_activity_history → get_activity → this tool), distinguishing it from nearby siblings.

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?

Explicitly states when to use ('场后要...'), and explicitly states when NOT to: '撞 404 时 join_activity_online 帮不上忙...别调' and '本域刻意不提供代发弹幕/提问'. The access-gate rule (public vs non-public activities) further clarifies eligibility. Alternatives and exclusions are named directly.

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