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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond that, such as what happens for an unknown id, whether activity data is live or cached, or what authorization is required.

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 a single front-loaded sentence with no wasted words. For a simple get-by-id tool this is appropriately concise, though it is terse enough that it sacrifices useful context.

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?

The tool is simple, the schema is fully described, and annotations cover read-only/open-world behavior, so the minimum needed to call it is present. However, with no output schema, the description does not say what an activity object contains or how errors are represented.

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 both parameters are already fully documented in the input schema. The description only restates that lookup is by id and does not add format, fallback, or channel-selection details beyond the schema.

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: 'Get one activity by id.' The singular 'one activity' and the id-based retrieval distinguish it from sibling list-oriented tools like activities_list and activities_top, though it does not explicitly name those alternatives.

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 implies the tool is used when retrieving a single activity by id, but gives no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as activities_list or activities_top.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one useful behavioral fact beyond that — results are 'newest first' — but says nothing about pagination semantics (before/after as cursors) or result volume/size.

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?

A single dense sentence that front-loads the resource and lets the enum-like clause trail. Zero wasted words.

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 10-parameter read-only listing tool with no output schema and no annotations covering pagination, the description should clarify how before/after act as page cursors and roughly what a record contains. As written it is adequate but leaves that gap for the agent to infer.

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 every parameter including before/after, types, and the min* thresholds is already documented in the schema. The description's 'filtered by type, date range and minimum amounts' merely summarizes what the schema states, adding no syntax or constraint details, so baseline 3 applies.

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 ('List the channel's activity feed') and enumerates the content types included, so the agent knows exactly what it returns. It does not differentiate itself from close siblings like activities_top or activities_get, which prevents a 5.

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?

There is no explicit when-to-use guidance, no exclusions, and no reference to alternatives such as activities_top (aggregate stats) or store_redemptions_list. The filter list hints at how to scope results, but the agent gets nothing on which sibling to pick.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the agent knows this is a non-idempotent side-effecting action that touches external state. The description adds the visible consequence (an alert appears on overlays), but does not disclose rate limits, permission needs, or whether the replayed alert counts against a live trigger consumer, so it only modestly extends the annotations.

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?

A single sentence with zero filler; the action and its effect are front-loaded, and the trailing example is short and earns its place by clarifying intent.

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 two-parameter, no-output-schema action tool whose safety profile is fully covered by annotations, the description supplies everything needed to invoke it correctly. It could be slightly richer by saying what happens if the activity id does not exist, but nothing essential 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 description coverage is 100%: both channel and activityId carry their own 24-char hex format notes and the channel default is documented in the schema. The description adds no parameter-level detail beyond that, so the schema baseline of 3 applies.

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 (replay) and resource (an activity's alert) and names the visible effect (on the channel's overlays), which separates it from reads like activities_get and mutations like activities_update. It stops short of naming an adjacent sibling such as overlays_action, so the differentiation is good but not explicit.

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?

"e.g. to re-show a follow or tip alert on stream" gives one concrete motivating scenario, which is enough to imply when the tool is useful. There is no guidance on when NOT to use it (e.g. re-sending is unnecessary if the overlay already fired) and no mention of alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond that – no return shape, ordering semantics, paging behavior, or auth expectations – so it contributes essentially nothing on top of the structured fields.

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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though the brevity is closer to under-specification than meaningful conciseness.

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 simple read-only ranking tool with a fully documented schema and no output schema, the definition is minimally adequate. It leaves the agent unable to disambiguate from the several sibling top/leaderboard tools, which a fuller description should address.

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 every parameter (type, limit, offset, period, channel) is already documented in the schema. The description's 'cheerers or tippers' and 'for a period' restate the type and period enums without adding syntax or format detail, making the baseline 3 appropriate.

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?

Names a specific verb ('List') and resource ('top cheerers or tippers') with the 'for a period' scope qualifier, which an agent can map to the ranking nature of the tool. It does not, however, differentiate itself from close siblings like tips_top, tips_leaderboard, or sessions_top, which the agent must resolve unaided.

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?

There is no statement of when to use this tool versus alternatives, nor any prerequisite or exclusion info. Given the crowded sibling set of top/leaderboard tools, the absence of routing guidance is a real gap.

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

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

Annotations already declare it as a non-read-only, non-idempotent, non-destructive open-world write, so the safety profile is covered. The description adds one genuine fact beyond the structured data: the upstream endpoint is undocumented and has no known body format, which tells the agent not to expect contract guarantees. It does not mention permissions, error behavior, or what happens to omitted fields.

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?

Two short sentences, the core action front-loaded, and the invocation hint placed second. Efficient and free of filler, though the framing about StreamElements documentation is slightly verbose.

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 3-parameter mutation with no output schema and full schema coverage, the description is honest about the upstream documentation gap but leaves the agent without actionable knowledge of which fields can be changed, what authorization is needed, or how failures surface. It is adequate but visibly incomplete for a write operation.

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 restates that fields-to-change go in `changes`, but `changes` is an unconstrained object (additionalProperties: {}), and the description does not enumerate any valid field names or value shapes, so it adds little beyond the schema.

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 ('Update an activity'), which is unambiguous against read-oriented siblings like activities_list, activities_get, and activities_replay. It does not explicitly name those siblings as alternatives, so it stops short of a 5.

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?

The only usage direction is the invocation mechanic 'pass the fields to change in `changes`.' There is no statement of when to use this tool versus activities_list/activities_get/activities_replay, no prerequisites or permission context, and no indication of what a valid update requires.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful domain context about counters being updated by commands, but says nothing about behavior for a missing counter, error cases, or scope beyond 'current value'.

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?

A single front-loaded sentence with the return ('current value') stated first and the clarifying parenthetical doing real work. Nothing 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?

For a two-parameter read tool with a fully described schema and annotations covering safety and open-world access, the definition covers what the tool returns and what a counter is. Only edge-case behavior (nonexistent counter, default channel) is left implicit, and the channel default is already in the schema.

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%: both 'counter' and the optional 'channel' (with its default resolution rules) are fully documented in the schema. The description adds no syntax or format detail beyond restating that the counter is named, so the baseline 3 applies.

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 ('Get the current value of a named bot counter') and the parenthetical defines what a bot counter is, tying it to commands and the ${count} placeholder. There are no competing counter siblings to distinguish from, so the lack of explicit sibling differentiation costs little.

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?

The description explains what a counter is but never says when to call this tool versus alternatives, nor mentions prerequisites or that the counter must already exist. Usage is only inferable from the tool name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description goes beyond them by naming exactly what status fields come back (joined, muted, language, name), which is meaningful behavioral context given there is no output schema. It does not cover auth requirements or the fallback behavior of the channel parameter, keeping it out of 5 territory.

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?

A single sentence with zero filler, front-loading the verb and resource before the returned-field list. Nothing is redundant and nothing needs trimming.

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 zero-required-parameter read tool with no output schema, the description supplies the field list an agent would otherwise lack, and annotations carry the safety profile. The only gap is the absence of guidance on the optional channel parameter's fallback and no routing to related read tools.

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% and the single 'channel' parameter is fully documented in the schema, including the SE_CHANNEL_ID fallback. The description adds nothing about the parameter, so the baseline of 3 is appropriate.

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 (Get) and resource (the StreamElements chat bot's status on the channel) and enumerates the exact fields returned: joined state, muted state, language, name. That makes it clearly distinct from the mutation siblings (bot_join, bot_mute, bot_set_language) to any agent scanning the list. It stops short of naming those siblings explicitly, so it is short of a 5.

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?

There is no when-to-use guidance, no prerequisite/caveat, and no reference to alternative tools such as channels_get or users_channels. The only usage signal is implicit in the word 'status'. An agent must infer that this is the read counterpart to bot_join/bot_mute.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds nothing beyond that: it does not mention auth/scope requirements, what happens if the bot is already joined, or error behavior. With annotations carrying the burden, this is a bare-minimum contribution.

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?

A single front-loaded sentence with zero filler. It is appropriately short for a simple action, though it is arguably too sparse rather than concise in content.

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 one-parameter, zero-required, non-destructive action with an idempotent annotation and no output schema, the definition is minimally adequate. It still omits the sibling relationship (bot_leave) and any failure/permission context an agent might need.

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?

One optional parameter with 100% schema description coverage, including the 24-char hex format and the SE_CHANNEL_ID/token-owner default. The description contributes nothing about the channel argument, so the baseline 3 applies — the schema does all the work.

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: 'Make the StreamElements bot join the channel's chat.' An agent immediately knows the effect. It does not, however, distinguish itself from the obvious sibling bot_leave or explain the relationship to bot_get/bot_mute.

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?

No when-to-use guidance, no prerequisites (e.g., bot_get to verify current state, or whether the bot service must be enabled), and no reference to bot_leave as the inverse operation. The agent must infer the context from the tool name alone.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the mutation and reversibility profile is covered. The description adds the concrete consequence beyond the annotations: commands and timers stop working until rejoin, which is exactly the side-effect context an agent needs. It does not contradict destructiveHint=false, since the effect is reversible.

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?

Two tight sentences with the action front-loaded and the consequence second. No filler, and the plural 'timers' correctly scopes the impact.

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 zero-required-parameter mutation with a fully documented schema and no output schema, the description covers purpose, reversibility hint, and side effects. The only missing piece is explicit routing to bot_join and a note on auth/scope requirements.

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% and the single 'channel' parameter is fully documented in the schema (format, default fallback). The description adds nothing about the parameter, so the baseline 3 applies.

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 ('leave' with the '(part)' clarification for Twitch terminology) and resource ('the channel's chat'), and the second clause explains the observable effect. It is immediately distinguishable from the sibling bot_join.

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?

Usage is implied: the tool is for taking the bot out of chat, and 'until it rejoins' hints that the action is temporary and reversible. However, it never explicitly names bot_join as the counterpart or states the conditions under which an agent should prefer leaving over muting.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds the permission-scale semantics (which number means which role), but says nothing about auth requirements, what happens to a previously assigned level, or whether a bot/user identifier is needed.

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?

Two sentences, zero waste: the purpose is front-loaded and the enumeration that follows is dense, scannable data rather than filler. Nothing could be removed without losing actionable 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 3-parameter mutation tool with 100% schema coverage and annotations covering safe/write/idempotent behavior, the description covers what the tool does and the full level scale. The only real gap is interaction semantics (overwriting an existing level, or removing one via the sibling tool), which is a minor omission here.

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, but the description adds genuine value with a full 7-tier enumeration (100/250/300/400/500/1000/1500) for a non-enum integer parameter, exceeding the schema's two-example hint. It still does not clarify the username/channel parameters, but those are well documented in the schema.

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 ('Give a user a custom bot permission level') that maps cleanly to bot_levels_add and distinguishes it from siblings like bot_levels_list and bot_levels_remove. It does not explicitly name the remove sibling, so an agent still infers the boundary from the name alone.

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?

No when-to-use or when-not-to-use guidance is given; the tool is never contrasted with bot_levels_remove (to unset) or bot_levels_list (to inspect). The level table hints at how to pick a value but says nothing about when this operation is appropriate or what prerequisites exist.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description does add genuinely useful domain context by defining the permission-level scale (100 everyone ... 1500 broadcaster), which helps interpret results, but it says nothing about return shape, pagination, or whether only non-default custom levels are returned.

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?

Two sentences with the purpose front-loaded before the reference data. The level legend is dense but earns its place as interpretive aid; nothing is redundant or padded.

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 one-parameter, read-only list tool with no output schema, the description conveys what the result is (users with a custom bot permission level) and how to read the level values. The main omission is any hint about result size or pagination behavior.

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?

There is a single optional parameter with 100% schema description coverage, so the schema already explains the channel id format and the SE_CHANNEL_ID default. The description adds nothing about the channel parameter, which is the expected baseline when the schema does the heavy lifting.

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 with a qualifying scope: 'List users that have a custom bot permission level on the channel.' The scope ('custom bot permission level') keeps it distinct from generic user listing and the sibling add/remove operations. It does not explicitly name siblings, so it falls short of a 5.

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?

There is no guidance on when to use this versus alternatives (e.g., users_channels, users_access, or the bot_levels_add/remove siblings), nor any stated prerequisites. The permission-level enumeration describes returned data values, not when to invoke the tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description contributes a genuinely non-obvious behavioral fact — that removal reverts the user to their default level rather than leaving them level-less — which is not derivable from the structured fields. It still does not say what happens if no custom level exists or what the call returns.

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?

A single sentence with the operation front-loaded and the side effect trailing; no filler, no restatement of the title beyond what is needed.

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 two-parameter, destructive, idempotent mutation with a fully documented schema and no output schema, the description covers the essential effect and annotations cover safety. However, the absence of any routing guidance versus bot_levels_add and the silence on the channel parameter leave real gaps for an agent operating among ~100 siblings.

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%, with both username and channel fully documented in the schema (including the channel fallback to SE_CHANNEL_ID). The description only alludes to the 'user' being acted on and never mentions channel scoping, so it adds nothing beyond the schema — the correct baseline here is 3.

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?

Specific verb (Remove) plus resource (a user's custom bot permission level), which cleanly separates it from siblings bot_levels_add and bot_levels_list without needing to name them. It stops short of explicitly naming those siblings, so it misses the top mark, but an agent can identify the operation unambiguously.

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?

There is no when-to-use guidance, no distinction from bot_levels_add (which presumably sets the very level this tool removes), and no prerequisites such as required permissions or whether the username must already hold a custom level. The reader is left to infer usage from the verb alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only that each module's settings are returned; it says nothing about permissions, channel resolution behavior, or the shape of the result beyond a vague "settings" mention.

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?

A single front-loaded sentence with a useful parenthetical illustration and no filler. Nothing is wasted, though it is short enough that a little more substance could have been added without bloat.

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 simple read-only list tool with full parameter coverage and safety annotations, this is largely adequate. However, with no output schema, the description does not indicate what the returned modules or their settings look like, leaving a modest gap.

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% and the single optional channel parameter is fully documented in the schema (24-char hex, default resolution order). The description adds no parameter meaning of its own, so the baseline of 3 applies.

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 ("List the chat bot's modules") and clarifies the resource with concrete examples (8ball, roulette, duel, heist) and the fact that settings are included. This is clear enough to separate it from bot_get or bot_levels_list, though it never names or contrasts a sibling explicitly.

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?

There is no guidance on when to call this versus adjacent tools such as bot_get, bot_counter_get or bot_levels_list, and no prerequisites or caveats are stated. Usage is only implied by the verb "List."

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

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

Annotations already cover the safety profile (non-destructive, idempotent, open-world), so the bar is lower. The description adds genuine behavioral context beyond them: the bot remains in the channel rather than being removed, which tells the agent the change is a reversible state toggle.

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?

One sentence, front-loaded with the action, and the clarifying clause directly explains the observable behavior. Nothing 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?

For a one-optional-param tool with no output schema, the description is nearly sufficient: it explains the effect and the retained channel presence. It could note that unmuting is handled by bot_unmute, but nothing required to invoke the tool 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 100% and the single optional channel parameter is fully documented in the schema, including its default fallback. The description adds no parameter meaning, so the baseline 3 applies.

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 ('Mute') and resource ('the bot') and clarifies the effect: the bot stays in chat but stops sending messages. This implicitly separates it from bot_leave and bot_unmute, though it never names those 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?

Usage is only implied — the agent can infer this is for silencing the bot without removing it. There is no explicit when-to-use statement, no mention of the bot_unmute counterpart, and no prerequisites (e.g. token permissions) called out.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false. The description contributes one genuinely useful behavioral fact not in the annotations: the message is publicly visible to everyone in chat, which rules out a private/whisper interpretation. It says nothing about rate limits, required bot presence, or moderation filters.

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?

Two short sentences, front-loaded with the core action, with no filler. The second sentence is somewhat redundant with "chat" in the first, but it does carry the visibility 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 simple two-parameter messaging tool with full schema coverage and no output schema, the description covers the essentials. Minor gaps remain around prerequisites (bot joined, permissions) and rate limiting, but nothing that would cause an agent to call it incorrectly.

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% and the schema already documents both the optional channel default (SE_CHANNEL_ID/token owner) and the message constraints. The description's only parameter-adjacent signal is "the channel's chat," which adds nothing beyond what the schema states. Baseline 3.

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 ("Send a message to the channel's chat") plus the acting identity ("as the StreamElements bot"). It is clearly distinguishable from the other bot_* siblings (join, leave, mute, unmute, set_language, get), though it never names them explicitly.

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?

No when-to-use or when-not-to-use guidance is given. It does not say whether the bot must already be joined to the channel, whether this is for public announcements only versus whispers/DMs, or how it relates to siblings like bot_join.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so safety and repeatability are covered. The description contributes one useful behavioral detail beyond that — that only built-in responses are affected, not custom commands — but says nothing about whether the change persists, takes effect immediately, or requires specific permissions/plan level.

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?

A single front-loaded sentence with zero filler; the verb, resource, and scope qualifier arrive in one pass. Nothing could be cut without losing 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 simple idempotent setter with 100% schema coverage and annotations covering mutability, this is roughly adequate. It is thin, though: an agent cannot tell whether the setting is per-channel, whether it overwrites a previous value, or what confirmation the call returns.

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 both parameters (channel, language) are already documented in the schema with an ISO-code example and a channel-id default rule. The description adds no parameter-level meaning, so the baseline 3 applies.

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 (Set) and resource (the bot's language) and adds a meaningful scope qualifier: it governs 'built-in responses'. That distinguishes it from the other bot_* siblings (bot_say, bot_mute, bot_levels_*), though the description itself never names those siblings or explicitly excludes them.

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?

There is no when-to-use guidance, no prerequisites, and no alternatives mentioned. An agent gets no signal about when this tool is appropriate versus the rest of the bot_* family, nor about whether the channel parameter needs to be supplied or defaults automatically.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the agent knows the safety and repeat-call profile. The description adds only the outcome ('sends messages in chat again'), with no mention of required permissions, whether the unmute persists across sessions, or error behavior when the bot is not muted.

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?

A single short sentence that front-loads the action and wastes no words. Appropriate size for a zero-required-parameter state toggle.

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 simple, single-parameter, no-output-schema state change with annotations covering the safety profile, the description is nearly sufficient. It would be complete with a brief note on the muted precondition and how the channel default 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?

There is exactly one optional parameter, and schema coverage is 100% — the schema fully documents 'channel' (24-char hex, default resolution order). The description adds nothing about the channel parameter, so the baseline 3 applies since the schema carries the load.

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 ('Unmute') and resource ('the bot'), and the trailing clause clarifies the observable effect ('sends messages in chat again'). It is clearly the inverse of the sibling bot_mute, though it never names that sibling explicitly.

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?

Usage is only implied: an agent can infer this should be called when the bot is muted, but the description never states prerequisites (e.g., bot must currently be muted) or contrasts with alternatives. No when-not guidance is given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful context by naming the three third-party providers the result aggregates, but says nothing about auth requirements, rate limits, or result shape. Modest added value above annotations.

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?

One sentence, front-loaded with the verb and resource, with the provider list as a tight appositive. Nothing is redundant or padded.

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 zero-required-param read tool with a fully documented schema, no output schema, and annotations covering the safety profile, the description is sufficient. It could note the return shape or that results are read-only aggregates, but nothing essential for correct invocation 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 description coverage is 100% and the single optional 'channel' parameter is fully documented in the schema (24-char hex, defaulting behavior). The description adds no parameter semantics beyond what the schema provides, so the baseline 3 applies.

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 ('List') and resource ('emotes usable on a channel'), and goes further by enumerating the three source providers (Twitch, BTTV, FFZ). No sibling tool covers emotes, so an agent can identify it uniquely 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?

The purpose strongly implies when to reach for it (when you need a channel's emote set), but the description gives no explicit conditions, prerequisites, or alternatives. For a simple single-resource read tool this implied usage is adequate, but no routing guidance is offered.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the useful qualifier that only 'public' details are returned, hinting at a visibility restriction, but says nothing about return shape or rate limits.

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?

A single efficient sentence with the verb, resource, and identifiers front-loaded. No filler, though it could be slightly more informative at the same length.

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 one-parameter read-only tool with full schema coverage, the description is adequate but thin: it does not clarify what 'public details' includes or how it differs from channels_get_details. No output schema exists, so some return-value context would have helped.

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 the single 'channel' parameter (id, name, defaults to your channel) is already fully documented in the schema. The description restates id-or-name but adds no format or default semantics beyond it.

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 (Get) and resource (StreamElements channel) plus the accepted identifiers. The 'public details' qualifier hints at scope, but it does not clearly differentiate from siblings channels_get_details or channels_me, which an agent would have to resolve on its own.

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?

There is no when-to-use guidance, no mention of when to prefer channels_me or channels_get_details, and no prerequisites. Usage is only implied by the description text.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile and cross-boundary nature are covered. The description adds the shape of the returned payload, which is useful, but says nothing about auth/scopes, whether the token owner's channel is used by default, or rate limits.

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?

A single front-loaded sentence with the resource first and the payload parenthetically enumerated; nothing is wasted. It is terse rather than padded.

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 one-optional-parameter read tool with no output schema, the description compensates by naming what is returned (profile, settings, provider info) and the annotations carry the safety profile. The remaining gap is that it does not help the agent disambiguate from channels_get/channels_me.

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% and the single optional "channel" parameter is already fully documented there, including the SE_CHANNEL_ID/token-owner default. The description adds no syntax, format, or override semantics beyond the schema, so the baseline 3 is correct.

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 ("Get extended details for a channel") and enumerates the payload (profile, settings, linked provider information), so the agent knows what it retrieves. However, it never distinguishes itself from the closely-named siblings channels_get and channels_me, so the agent must guess which one to pick.

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?

There is only a weak implicit hint in the word "extended" that this returns more than a basic channel fetch. No when-to-use condition, no prerequisites, and no routing against channels_get or channels_me is provided.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful context beyond that: the call is bound to the configured token rather than an arbitrary channel, and it enumerates the returned fields (_id, username, display name, provider, avatar), which matters because there is no output schema.

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?

Two short sentences, front-loaded with the resource and the token scoping. 'and more' is slightly imprecise filler, but overall the text is efficient with no wasted preamble.

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 parameterless read with no output schema, the description carries the return-shape burden and mostly does so by naming the key fields. It stops short of a complete field list ('and more') and says nothing about error behavior when no token is configured, but nothing essential for invoking it 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?

The tool takes no parameters (empty schema, 0 required), so there is nothing for the description to disambiguate. Baseline for a zero-parameter tool is 4; the field list is the only useful addition and it belongs to returns, not inputs.

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 ('Get the StreamElements channel that owns the configured token') and scopes it to the token-bearing channel, which implicitly separates it from siblings like channels_get / channels_get_details that require an id. It never names an alternative explicitly, so sibling differentiation is inferred rather than stated.

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?

One usage cue is given: 'Use it to find your channel id', which tells the agent a common scenario. There is no when-not guidance, no mention of prerequisites, and no routing against channels_get or users_current, which are the plausible alternatives for identity lookups.

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

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

Annotations already flag destructiveHint=true/openWorldHint=true, but the description goes well beyond them: it discloses that the token being revoked may be the one this MCP server itself uses, that every subsequent call will fail, and that recovery requires writing a new value to SE_JWT_TOKEN / SE_OAUTH_TOKEN. It also honestly marks the endpoint as undocumented rather than asserting unverified behavior.

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?

Three sentences, front-loaded with the route and action, then the risk warning, then the usage gate — ordered by decreasing importance. No filler; every clause carries information the agent needs.

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 single-parameter, no-output-schema mutation tool, the description covers effect, uncertainty, blast radius, and recovery path. Nothing material is left for the agent to infer before deciding whether to call it.

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% and the single optional 'channel' parameter is fully documented in-schema, including its SE_CHANNEL_ID default. The description adds no extra syntax or format detail beyond the schema, so the baseline 3 applies.

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 the exact HTTP verb and route (DELETE /channels/{channel}/accesstoken) plus a plain-language gloss of the effect, so the agent knows precisely what resource is being acted on. No sibling tool in the list concerns token revocation, so it is trivially distinguishable.

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 an explicit when-to-use gate: 'Only run it if the user explicitly asks for it.' It also supplies the consequence that motivates that restriction (later calls fail), which is exactly the decision context an agent needs before invoking a one-way operation.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the POST in the description is consistent with a non-read-only call. Beyond that, the description adds a genuinely useful meta-signal: the upstream API is undocumented and the side effects are unknown, which is real context an agent needs. It still does not disclose auth requirements, what succeeds/destroys, or the response behavior.

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?

Three short sentences, front-loaded with the route, with no padding. The middle sentence about StreamElements documenting the endpoint without a description is meta-commentary that could be compressed, but nothing is bloated.

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 POST with no output schema and unknown semantics, the description leaves the agent without any means of predicting the effect or even confirming the call is safe to make. Honesty about the gap is better than fabrication, but the definition still does not give enough to invoke the tool confidently.

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% with a single optional parameter, and the schema already documents the channel id format and its SE_CHANNEL_ID fallback. The description adds nothing about the parameter, so the baseline of 3 applies.

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 gives the raw HTTP route and admits the purpose is unknown ('appears to relate to the channel's realtime socket connection'), so it never states a concrete verb+resource an agent can act on. It is more informative than a bare tautology, but it stops short of telling the agent what the tool actually does.

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?

'Only use it if you know what it does' is an explicit warning against use, which has some routing value. However, it names no alternatives among the many siblings (channels_get, sessions_get, etc.) and gives no positive condition for when this call is appropriate.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond restating the title: it does not describe the time window the 'per minute' stat covers, the return shape, or how the limit/pagination behaves.

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?

A single, front-loaded sentence with no filler. It is efficient, though arguably too terse for a stats tool where scope and time window matter.

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?

The tool is simple, annotations cover safety, and the schema is complete with no output schema required. Still, an agent gets no sense of what the returned stat looks like or over what period 'per minute' is aggregated, leaving a minor gap.

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%, with 'username' and 'limit' both documented in the schema, so the baseline is 3. The description adds no parameter meaning beyond what the schema already provides.

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 ('Get') and resource ('emotes per minute chat stats') scoped to 'a channel's', which tells the agent this is per-channel rather than global. It is clear on its own, but it never names the sibling (e.g. chatstats_global) that would be the alternative for non-channel stats.

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?

There is no explicit when-to-use or when-not-to-use guidance. The phrase 'a channel's' weakly implies a per-channel scope, but the description never tells the agent how this differs from chatstats_global, chatstats_stats, or chatstats_get.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description contributes nothing on top of that. It does not disclose the aggregation window, whether the channel must be live, or any auth/rate-limit constraint that an openWorld read against a third-party channel would imply.

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?

A single front-loaded sentence with zero filler. It is efficient, though the same brevity that keeps it clean is what leaves the sibling disambiguation and return-shape gaps unaddressed.

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 burden of telling the agent what a 'chat stats summary' returns, and it does not. Combined with the absence of any differentiation from the other chatstats_* tools, the definition is too thin for an agent to call confidently.

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% and the schema itself defines 'username' well (lowercase login name, not an id). The description only echoes 'by channel name', adding no format, case-handling or lookup-failure detail beyond the schema, so the baseline 3 applies.

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 clear verb and resource ('Get a channel's chat stats summary'), narrowed by an identifier ('by channel name'). However, the word 'summary' is undefined and it makes no attempt to distinguish itself from chatstats_global, chatstats_stats, chatstats_item, chatstats_search or chatstats_epm, which an agent must choose between.

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?

No when-to-use guidance and no alternatives named, despite six sibling chatstats_* tools in the same namespace. The agent is given no cue about when this is the right call versus chatstats_stats or chatstats_item.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds the scope qualifier ('all channels that StreamElements chat stats tracks') but says nothing about pagination behavior, result shape, or freshness of the stats, so it adds only modest context beyond the structured fields.

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?

One sentence, front-loaded with the verb and scope, with no filler or repetition of the title. Mildly under-specified rather than bloated, which is the only thing keeping it from 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 ideally would say what the statistics contain (viewer counts, messages, time window). Instead it leaves the return payload entirely undefined, which is a real gap for a stats query, though the read-only annotations and documented paging params cover the invocation basics.

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% for both limit and offset, so the schema already explains paging. The description adds no syntax, default, or range information beyond that, so the baseline 3 applies.

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 ('Get global chat statistics') and adds scope ('across all channels'), which separates it from a channel-scoped sibling like chatstats_get. It does not, however, name or compare against the other chatstats_* siblings (stats, epm, item, search), so the agent must infer the distinction.

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?

No when-to-use or when-not-to-use guidance is given, and no alternative is named. With five sibling chatstats tools, the description offers nothing to route an agent toward the right one.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only that the lookup is scoped to a single item in a category; it does not describe return shape, pagination, or other behavioral details. A 3 is appropriate with annotations carrying the safety burden.

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?

A single sentence with no wasted words, front-loading the action and resource. It is appropriately terse for a simple read-only lookup, though extremely minimal.

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 simple read-only tool with full schema coverage and annotations, the description is minimally adequate: it states what the tool does and scopes it to one item. However, with no output schema and no usage routing, it leaves the agent to infer when to choose it and what the response contains.

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 three parameters are already documented in the schema with examples. The description reinforces the 'item' concept but adds no syntax, format, or constraint details beyond what the schema provides. Baseline 3 applies when the schema does the heavy lifting.

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 ('Get the chat stats for one item in a category') and gives examples that clarify scope. It does not, however, differentiate itself from sibling chatstats tools such as chatstats_get or chatstats_stats, so it falls short of a 5.

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?

There is no explicit guidance on when to use this tool versus the other chatstats siblings, nor any when-not conditions. The examples ('one emote or one chatter') hint at the use case but do not tell an agent how to choose this over alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description usefully narrows the search space to channels actually tracked by chat stats rather than the whole platform. However, it omits matching behavior (prefix vs substring vs fuzzy) and whether multiple results are returned, which are the traits an agent would most need here.

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?

A single front-loaded sentence with no padding or restatement of the title. It is efficient, though the terseness leaves no room for the behavioral detail that would make it more useful.

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 one required parameter fully documented in the schema, no output schema, and safe read-only annotations, the core call is callable. The description still leaves the result shape and matching semantics unspecified, which is a real gap for a search tool with no output schema.

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% and the schema already specifies 'Channel name (lowercase login name, not an id)', including the lowercase-login constraint. The description's 'by channel name' adds nothing beyond that, so the baseline 3 applies.

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 (search) and resource (channels tracked by chat stats) scoped by channel name, which distinguishes it from stat-reading siblings like chatstats_stats or chatstats_epm. It stops short of explicitly contrasting with chatstats_get, so differentiation is inferred rather than stated.

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?

There is no when-to-use guidance, no statement of prerequisites, and no named alternative for looking up a specific channel's stats (chatstats_get). Usage must be inferred entirely from the verb.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the scope of returned data categories, which is mild behavioral value, but says nothing about auth requirements, rate limits, or whether stats are per-session or all-time.

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?

A single front-loaded sentence with no padding. The trailing 'and more' is slightly vague but costs little, and nothing needs trimming.

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 does the minimum by naming the main data categories, but omits pagination behavior despite the limit parameter and does not clarify the relationship to the other chatstats endpoints. Adequate but with visible gaps.

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%, with both username (lowercase login name) and limit (items per page) documented in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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 clear verb and resource ('Get a channel's detailed chat stats') and enumerates the content categories returned (top chatters, emotes, commands, hashtags). It is clear on its own, but it does not differentiate itself from close siblings like chatstats_get, chatstats_global, or chatstats_search, leaving the agent to guess which of the five chatstats tools this is.

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?

There is no guidance on when to use this over the sibling chatstats tools, nor any prerequisites or exclusions. The description only says what the tool returns, not the situation that selects it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is known. The description adds nothing behavioral on top of that — it never mentions auth/channel requirements, what happens if the command name already exists, or the effect of creating a command on the live channel.

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?

It is a single, front-loaded sentence with no wasted words. But for a 14-parameter creation tool with nested objects it is under-specified rather than genuinely concise, so it does not reach the top of this dimension.

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 create operation with 14 parameters, two required fields, nested cooldown/accessLevel objects, and no output schema, the single sentence leaves the agent without side-effect, prerequisite, or failure-mode context. Annotations cover only the safety profile; the description does not fill the remaining gaps.

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% across all 14 parameters, including required 'command' and 'reply' and nested cooldown/accessLevel semantics, so the schema carries the full burden. The description contributes no additional parameter meaning (no default behavior, no explanation of type 'say' vs other modes), which is the baseline 3 when schema coverage is complete.

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 names a specific verb and resource ('Create a custom chat bot command'), so the basic action is unambiguous. However, it is almost a verbatim restatement of the title 'Create custom command' and adds no differentiation from siblings such as commands_update or commands_delete, so it goes little beyond the name.

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?

There is no when-to-use guidance, no prerequisites, and no mention of the closely related commands_update / commands_list siblings. The agent gets no signal about when creating is appropriate versus updating an existing command.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description reinforces irreversibility with 'Permanently', but adds nothing about behavior on a non-existent or already-deleted commandId, whether the command disappears from commands_list immediately, or any cascade effects.

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?

A single six-word sentence with the destructive qualifier front and center — nothing wasted and nothing buried. However, the brevity edges toward under-specification for a destructive operation rather than being a model of economical completeness.

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?

The tool is simple (2 params, 1 required, no nesting, no output schema) and annotations carry the safety semantics, so the description is close to sufficient. It still omits failure modes and scoping effects that matter for an irreversible delete, leaving it at minimum viable.

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%: commandId is documented with its 24-hex pattern and channel is documented with its default resolution rule. The description adds no parameter detail whatsoever, so the baseline 3 applies.

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 (delete) and resource (custom command), which cleanly separates it from commands_create, commands_update, and commands_get amongst the siblings. The adverb 'Permanently' adds a meaningful qualifier. It does not explicitly name a sibling alternative, so it stops short of a 5.

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?

There is no guidance on when to delete versus update (e.g., commands_update for renaming), no preconditions such as ownership or channel scoping, and no warning to confirm with the user before an irreversible action. The agent must infer all of this.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond that — no mention of what is returned, whether missing ids error, or channel scoping behavior.

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?

A single short sentence with the key lookup constraint (by id) front-loaded and zero filler. Nothing could be removed without losing 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 simple read-by-id tool with annotations covering safety this is nearly sufficient, but with no output schema the description should at least hint at what a retrieved command contains or what happens on an unknown id. The channel parameter's scoping role is also left entirely to the schema.

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%, including format and default details for channel and commandId, so the schema carries the load. The description's 'by id' only reaffirms the required parameter and adds no new semantic detail, matching the baseline for full schema coverage.

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 (Get) and resource (custom command) plus the lookup key (id), which distinguishes it from commands_list and commands_create. It does not explicitly name a sibling, so it falls short of a 5.

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?

There is no statement of when to use this versus commands_list, commands_list_public, or commands_list_default, and no prerequisites or context. The 'by id' phrasing implies you must already have a commandId, but that is inference, not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully discloses the shape of what comes back (replies, cooldowns, costs, access levels), but says nothing about pagination, result limits, or the fact that it defaults to the token's own channel — behavior an agent would want before calling.

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?

A single sentence with zero filler, front-loaded with the verb and resource and immediately followed by the payload details. Nothing could be trimmed without losing 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 parameterless-friendly read-only list call with annotations covering safety and no output schema, the description's field enumeration partly compensates for the missing return documentation. It remains incomplete on sibling disambiguation and pagination/result-size behavior, which matters in a family with three near-duplicate list tools.

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?

There is only one optional parameter (channel) and schema description coverage is 100%, so the schema already explains the 24-char hex format and the SE_CHANNEL_ID fallback. The description adds nothing about the channel parameter, which is the expected baseline when the schema does the heavy lifting.

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 (List) and resource (the channel's custom chat bot commands) and even enumerates the data returned (replies, cooldowns, costs, access levels). It does not, however, distinguish itself from the near-identical siblings commands_list_public, commands_list_default, or commands_get, so an agent cannot tell from the description alone which list endpoint to pick.

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?

There is no when-to-use guidance, no conditions, and no named alternative. With three sibling list/get tools for commands (commands_list_public, commands_list_default, commands_get) in the same family, the absence of any routing hint is a real gap.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only that returned items include each command's settings; it says nothing about pagination, channel-permission requirements, or the fallback behavior of the channel parameter.

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?

A single front-loaded sentence that names the resource, its examples, and its scope with no wasted words.

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?

No output schema exists, but the description notes the return includes commands and their settings, and both parameters are fully documented in the schema, so an agent has enough to invoke it correctly. Lacking only routing guidance against the several sibling list/get commands.

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% — both channel (with its fallback to SE_CHANNEL_ID/token owner) and language are fully documented in the schema. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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 (List) and resource (bot's built-in default commands) and adds clarifying examples (!points, !followage) plus the scope of returned data (their settings). It implicitly separates built-in defaults from the custom commands handled by commands_list/commands_create, but never names those siblings explicitly.

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?

Usage is implied — you call this to inspect the built-in command set — but there is no explicit when-to-use guidance, no statement of when to prefer it over commands_list, commands_list_public, or commands_get, and no preconditions mentioned.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the framing that results mirror the public StreamElements command page; it says nothing about filtering, ordering, or whether private/moderation commands are excluded.

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?

A single well-formed sentence with no filler and the key scope qualifier ('public') placed early. It is efficient, though it is arguably too terse to carry the differentiation the sibling set demands.

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 an optional-parameter, read-only list tool this is minimally adequate, and annotations cover the safety profile. With no output schema, however, the description leaves the return shape and the public-vs-all command distinction unaddressed, which is the main thing an agent would need.

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?

With one parameter and 100% schema description coverage, the schema already fully explains the optional 'channel' id and its fallback behavior. The description adds no additional parameter semantics, which matches the baseline 3 when schema coverage is complete.

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 gives a specific verb ('List') and resource ('the channel's public commands') and qualifies the scope with 'public', which hints at a distinction from commands_list. However, it never names the sibling it differs from, so an agent must infer the difference between this and commands_list / commands_list_default.

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?

Usage is only implied: 'public' suggests this is the tool for commands visible on the public command page, as opposed to all commands a moderator would see. There is no explicit when-to-use statement, no exclusion, and no named alternative, despite several near-identical siblings (commands_list, commands_list_default).

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

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

The annotations already declare the safety profile (not read-only, idempotent, non-destructive, open-world), so the bar is lower. The description adds genuinely useful information beyond them: the API may treat the payload as a full replacement, so omitted fields can be lost — a real behavioral hazard an agent must 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?

Two tight sentences with no filler. The core action leads, and the replacement hazard, the single most decision-relevant fact, follows immediately.

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 15-parameter mutation with nested objects and no output schema, the description covers the critical gotcha (full replacement) and points to commands_get for the correct payload shape. It leaves channel/token defaulting and permission requirements to the schema, which is acceptable given full coverage there.

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% across all 15 parameters, including nested cooldown fields, so the schema already carries the parameter meaning. The description adds only the meta-advice to reuse every field from commands_get, not any additional per-field semantics.

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 ('Update a custom command'), which is immediately distinguishable from create/list/delete siblings. It does not, however, differentiate itself from the closely named 'commands_update_default' sibling, which an agent could easily confuse it with.

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?

The description gives an actionable workflow hint by naming commands_get as the source of the full field set, implying a read-before-write pattern. It never states when this tool is preferred over the near-identical 'commands_update_default', and there are no exclusions or prerequisites about permissions or channel scoping.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the safety bar is lower here and nothing in the description contradicts them. The description adds concrete payload shapes but says nothing about whether unspecified settings are preserved or overwritten, nor about permission requirements for high accessLevel values.

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?

Two sentences, no filler, with the operation stated first and the id-sourcing hint last. The inline JSON examples add length but directly reduce invocation ambiguity for an untyped settings object.

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 three-parameter mutation tool with full annotations and no output schema, the definition covers the essentials: the target resource, the id source, and sample setting values. The main remaining gap is merge-vs-replace semantics for the settings object, which is only weakly implied by 'settings to change'.

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%, but the critical settings object is an open additionalProperties map with no documented keys, so the description's examples ('enabled', 'cooldown.user/global', 'accessLevel') carry real information the schema cannot. commandId sourcing from commands_list_default is also restated usefully, though channel is left to the schema.

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 (update/change) and resource (built-in default command settings), and the word 'default' distinguishes it from the sibling commands_update, which handles user-created commands. It does not explicitly name commands_update as the contrasting alternative, so differentiation is inferable rather than stated.

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?

The description routes the agent to commands_list_default for obtaining valid commandId values, which is genuinely useful usage guidance. However, it never states when to prefer this over commands_update or what preconditions (permissions, plan tier) must hold, leaving the main selection decision to inference.

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

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

Annotations already declare this is a non-read-only, non-idempotent, open-world mutation. The description adds the 'as the token owner' identity context but does not explain what gets deducted, what failure conditions exist, or whether the contest must be in a specific state. It adds some value beyond the annotations but not rich behavioral detail.

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?

A single front-loaded sentence with no wasted words. The action, target, and actor are all conveyed immediately, and nothing is padded or repeated.

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?

The schema is rich, annotations cover the safety profile, and no output schema exists, so return values need not be explained. However, for a betting mutation, the description omits relevant context like contest state requirements or what happens to the bettor's points, leaving it minimally adequate rather than fully complete.

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%, and the schema itself documents every parameter, including the optionID cross-reference to contests_get and the channel default. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline 3 is appropriate.

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 (Place) and resource (bet on a contest option), plus the actor (token owner). This clearly distinguishes it from sibling tools like contests_list_bets or contests_get, which list or retrieve contests rather than place bets.

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?

The description gives no when-to-use guidance, no prerequisites (e.g., contest must be open), and does not name alternatives. It simply states the action, leaving the agent to infer context from the name and schema.

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

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

Annotations already declare destructive=true, idempotent=true and openWorld=true, so the safety profile is covered. The description adds the state transition (bets no longer accepted) but says nothing about whether existing bets/funds are preserved, reversed, or locked pending payout — a meaningful gap for a destructive mutation.

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?

A single sentence, front-loaded with the action and resource, with the trailing clause earning its place by spelling out the observable effect. No filler or repetition of the title.

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 2-param mutation with annotations covering safety hints and no output schema, the essential call information is present. Missing are preconditions (valid contest state), whether existing bets are retained for settlement, and error behavior if betting is already closed.

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% and both parameters (channel, contestId) are fully documented in the schema, so the description carries no additional parameter burden. Baseline 3 is appropriate; the description adds no format or defaulting detail beyond the schema.

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 ('Close betting on a running contest') plus the resulting state ('no new bets are accepted'), which separates it from contests_draw_winner and contests_refund. It implies the sequencing rather than naming siblings outright, so it stops short of a 5.

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?

The clause 'before picking a winner' implies the correct moment to invoke it, which is real guidance. It does not name contests_draw_winner, contests_refund, or state prerequisites (e.g. contest must be open with bets placed), so usage is only implied.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive, open-world write. The description adds the lifecycle fact that the contest must be started separately, which is genuinely useful, but says nothing about auth requirements, whether an active session/loyalty module is needed, or what happens on a duplicate title.

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?

Two short sentences, zero filler, with the core purpose front-loaded and the follow-up action placed second. Nothing repeats the tool name or title unnecessarily.

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 7-parameter write with 2 required fields and a fully documented schema, the description plus annotations cover enough to invoke it correctly. The only gap is the absence of any hint about the return value (e.g., a contest id needed for contests_start/bet), which matters since there is no output schema.

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% and includes examples for title, options, command, channel and bet bounds, so the schema carries all parameter meaning. The description adds no extra syntax, defaults, or constraints beyond what is already documented, making the baseline 3 appropriate.

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 ("Create a contest") and adds the domain semantics (viewers bet loyalty points on an outcome), which tells an agent exactly what artifact is produced. It also names the sibling contests_start as the next step, implicitly distinguishing creation from activation and from contests_update/contests_list.

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?

"Start it with contests_start" gives explicit workflow sequencing that an agent would not otherwise infer, so it knows create alone does not launch betting. It stops short of when-not-to-use guidance (e.g., an already-running contest, missing loyalty module) or prerequisites such as required permissions.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds real value the annotations cannot: the naming collision with contests_close and the recommended alternatives. It stops short of stating the concrete consequence of deletion (e.g. what happens to existing bets), which keeps it from a 5.

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?

Three short sentences, front-loaded with the route and then the disambiguation. Efficient, though the raw route restatement partly duplicates the name/title rather than adding new 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 two-parameter destructive tool with no output schema, the description gives the agent what it needs to choose correctly among the contest siblings. The only modest gap is that it never states the side effects on contest state or bets beyond implying contests_refund is the way to return bets.

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% and both parameters are documented in the schema with formats. The description only echoes the path placeholders {channel}/{contestId} without adding syntax, defaults, or behavior beyond the schema, so the baseline 3 applies.

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 (DELETE contest) and immediately disambiguates via the underlying HTTP route. It further pins down the identity confusion by noting StreamElements labels this 'Close contest', the same as contests_close, so an agent can distinguish it from the near-identical sibling.

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?

Explicit routing guidance: 'Prefer contests_close to end a running contest and contests_refund to return bets.' It names both alternatives and the exact conditions that select them, leaving nothing to inference.

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

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

Annotations already declare destructive=true, non-idempotent, openWorld, so the safety profile is covered; the description still adds real value by stating the point-payout effect and, notably, honestly warning that the request body is undocumented and only presumed to be { "winnerId": "<option _id>" }. That caveat is exactly the kind of context annotations cannot 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?

Two sentences, front-loaded with the action and effect, then the body caveat. No filler; the only mild cost is the hedging 'presumably', which is justified given the genuinely undocumented payload.

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 destructive, non-idempotent settle operation, the description says points are paid out but does not say whether the contest is auto-closed, whether the action can be undone, or what happens to losing bettors. Annotations cover the safety flags and there is no output schema to explain, so it is adequate but leaves real gaps around side effects.

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% (baseline 3), but the schema types the 'winner' body as a free-form object with additionalProperties, so it offers almost no semantic guidance. The description compensates with a concrete example body shape (winnerId -> option _id), which meaningfully reduces the guesswork for the one non-obvious parameter.

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 ('Settle a contest by choosing the winning outcome') plus the consequence ('pays out points'). Combined with the tool name, an agent can distinguish it from the sibling giveaways_draw_winner and from contests_close/contests_refund 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?

Usage is only implied through the concept of settling a contest; there is no explicit statement of when to call this versus contests_close, contests_refund, or contests_bet, and no prerequisite (e.g., contest must be in a bettable/ended state) is given. Implied lifecycle context is present but no routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description adds that the response includes options, totals and state, which is useful payload context, but says nothing about permissions, error behavior for a missing/invalid id, or result freshness.

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?

A single sentence that front-loads the verb and resource, then lists what is returned. No wasted words and nothing important buried.

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 simple two-parameter read tool with no output schema, the description covers the essential fact that the response carries options, totals and state, and annotations cover safety. Missing only the error/missing-id behavior, which is a minor gap at this complexity.

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%, and the schema fully documents both contestId (24-char hex pattern) and channel (defaulting behavior). The description only alludes to the id parameter with 'by id' and adds no format or default detail beyond the schema — the baseline 3 applies.

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 ('Get one contest by id') and adds the payload shape ('options, totals and state'), which is more informative than a bare restatement. It does not name a sibling to contrast with (e.g., contests_list vs. contests_get), so an agent must infer the singular-vs-list boundary.

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?

There is no when-to-use guidance, no prerequisites, and no mention of the alternative tools (contests_list, contests_list_bets, contests_draw_winner). 'By id' implies a known-id lookup, but nothing states that condition or excludes the list variants.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds only the notion that results are historical; it says nothing about ordering, whether the list is bounded, or how paging behaves in practice, which is the value it could have added.

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?

A single short sentence with no filler and the resource front-loaded. It is appropriately sized, though it arguably errs on the side of under-specification for a tool that collides with a sibling name.

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 no-required-parameter list tool with full schema coverage and an existing readOnly annotation, the essentials are present. What is missing is the distinction from contests_list and any hint about result volume or paging, which an agent listing contests would need.

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% with three well-documented parameters (limit, offset, channel), so the schema carries the semantic load. The description contributes nothing beyond that, which lands at the baseline for a fully documented schema.

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 clear verb and resource ('List the channel's previous contests') and the word 'previous' scopes it to past/historical records. It does not, however, differentiate itself from near-identical siblings such as contests_list or contests_get, leaving the agent to guess which one returns historical data.

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?

There is no when-to-use guidance, no statement of prerequisites, and no named alternative. The agent is not told why it would pick contests_history over contests_list, even though the two names are nearly interchangeable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered by structured data. The description adds meaningful domain context ('points betting on outcomes') and discloses result scope ('including the active one'), but says nothing about ordering, completeness, or what happens on a channel with no contests.

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?

A single efficient sentence with the verb and scope front-loaded; nothing is wasted. It is arguably too terse for a tool with many contest-related siblings, but there is no padding or repetition.

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 simple read-only one-parameter list operation with no output schema and annotations covering the safety profile, the description is sufficient to call the tool correctly. Return-shape explanations are not needed since no output schema exists to contrast against, and the scope is stated.

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% for the single optional 'channel' parameter, so the schema already carries the semantics (24-char hex id, defaults). The description's 'the channel's contests' only restates that scoping and adds no format or fallback detail beyond the schema.

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 (list) and resource (contests), and adds a definitional gloss ('points betting on outcomes') plus the scope detail 'including the active one'. It does not, however, distinguish itself from the nearby contests_history or contests_list_bets siblings, which an agent must infer.

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?

Usage is only implied: the phrase 'including the active one' hints this returns current/all contests rather than a history or a single record, but there is no explicit when-to-use or when-not-to-use statement, and no sibling (contests_history, contests_get, contests_list_bets) is named as the alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds nothing beyond that: no mention of pagination, result ordering, whether contests must be closed, or what the returned bet records contain.

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?

A single front-loaded sentence with zero waste. It is efficient, though the brevity reflects some under-specification rather than dense 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?

Adequate minimum for a simple read tool: the schema covers both parameters and annotations cover safety. Still missing any note on result shape, pagination, or ordering, and no output schema exists to fill that gap.

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 both contestId and channel are fully documented in the schema (including the 24-char hex pattern and the SE_CHANNEL_ID default). The description adds no extra parameter meaning; baseline 3 applies.

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: listing bets placed on a contest. This is clearly distinct from contests_list (which lists contests), contests_bet (which places a bet), and contests_get. However, it does not explicitly name those siblings or spell out the distinction, leaving the agent to infer it.

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?

No when-to-use guidance, no exclusions, and no mention of alternatives. It never says to use contests_bet to place a bet or contests_list to enumerate contests, nor does it mention scope such as filtering by user or contest state.

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