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. The description adds the add/remove toggle and emoji format, but both are restated from the schema; no auth, rate-limit, or return behavior is disclosed.

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 tightly written sentences; the primary action is front-loaded and the remove=true qualifier is appended without 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 simple single-target action, the description plus rich annotations and full schema coverage is nearly sufficient. Minor gaps (rate-limit or permission behavior on an openWorld mutation) remain, but the include the dual mode and format options.

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 five parameters (including remove and format) are already documented in the schema. The description's emoji-format note duplicates the schema's own emoji description, adding no meaning beyond structured data; 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?

States a specific verb and resource ('adiciona/remove uma reacao... em uma mensagem') and clarifies the dual add/remove mode. Clear enough to distinguish from edit_message or send_message, though it doesn't name any 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?

The remove=true flag gives conditional usage for the inverse operation, which is genuine guidance. However there is no explicit when-to-use vs alternatives context or prerequisites (e.g., needing access to the channel).

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 non-readOnly, non-idempotent, non-destructive, open-world behavior. The description adds genuinely useful context beyond that: content is mandatory in forums, tags are forum-only, and content becomes the first message of a standalone thread. It omits permission/auth requirements and archive behavior (left to the 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 dense sentences, front-loaded with the forum case and then the text-channel branch, with zero filler. Every clause carries a behavioral rule the caller 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 7-parameter mutation tool with no output schema, the critical mode-dependent logic is fully covered, and remaining details (format, autoArchiveMinutes defaults) live in the schema. It does not hint at the returned shape, which is a minor gap given no output schema exists.

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 description adds conditional semantics the schema cannot express: content is required only in the forum branch, tags apply only to forums, and messageId presence/absence changes the operation. That is real added meaning over the flat parameter list.

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 (cria) plus resource (thread/post) and splits the behavior by context: forum post vs. text-channel thread. This distinguishes it clearly from siblings like send_message, reply_message and join_thread without needing to open 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?

The description gives explicit conditional guidance: in a forum it creates a post, in a text channel messageId selects 'thread from message' vs. 'standalone public thread'. It does not name an alternative sibling or state when NOT to use it (e.g., use reply_message for plain replies), so it falls short of a 5.

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 and idempotentHint=true, so the safety profile is largely covered. The description adds the permission requirement for deleting others' messages and states 'Irreversivel', which reinforces but does not substantially extend what destructiveHint already conveys. It says nothing about rate limits or failure modes.

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 compact sentence: verb, resource, scope condition, and the irreversibility caveat. Every clause earns its place and the destructive warning is front-loaded rather than 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 destructive mutation with full annotation coverage, a complete parameter schema, and no output schema, the description covers what is being deleted, whose message, the permission gate, and irreversibility. It is nearly sufficient; only explicit alternative-tool routing 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%, so channelId, messageId and format are fully documented in the schema. The description adds no per-parameter meaning (no format details, no id-format notes). Baseline 3 is appropriate when 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 (delete) and resource (a message), and clarifies scope: own messages, or others' if the account has moderation permission on the channel. This distinguishes it cleanly from sibling mutations like edit_message or send_message. It stops short of naming a specific alternative, so a 4 rather than 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 description implies when the tool applies and gives one real condition (moderation permission needed to delete others' messages), but it offers no explicit when-not guidance and never names an alternative for cases where deletion is undesirable (e.g. edit_message). Usage is implied rather than directed.

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 genuinely useful behavior beyond that: it reassures no sensitive data is exposed and that it still responds when the token is invalid, which is important for diagnosing auth failures. It stops short of describing pagination or limits' semantics.

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 what is shown and ends with the key caveat about invalid tokens. No filler, no tautology.

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, and the description compensates by enumerating the returned fields (account, mode, gateway, channels, cursors, limits, statistics). Combined with annotations covering safety and the fully-described single parameter, an agent has enough to call it correctly; only the return shape's exact structure is left implicit.

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% — the single 'format' enum parameter is fully documented in the schema with the text (default) vs json distinction. The description adds nothing about the parameter, which is acceptable given the schema does the work, 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 ('Mostra') and enumerates the concrete resource set: connected account, mode (user/bot), live gateway, watched channels, cursors, limits and statistics. An agent can tell this is a diagnostics/status tool, clearly distinct from the messaging and guild-management siblings. It lacks an explicit sibling comparison, but the enumeration makes the purpose unambiguous.

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 explicit 'use this when' or 'don't use for X' guidance is given, but the content list plus 'Responde mesmo com o token invalido' strongly implies a connectivity/diagnostics use case, including troubleshooting when auth fails. Usage is inferable but never stated as a condition.

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. The description usefully adds that only messages sent by this account can be edited, but says nothing about permission failures, rate limits, or how edits surface to other users.

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 redundant or filler content, and the scope constraint is stated up front. It is efficient, though it is so terse that it borders on under-specification rather than optimal 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 edit operation, the schema fully documents inputs and the annotations carry the behavioral profile, so the description's core job is naming purpose and scope — both of which it does. Only edge-case behavior (editing a message once it is no longer editable) is unaddressed, which is 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%, so all four parameters (including the format enum and the 2000-char content limit) are already documented. The description adds no syntax or format detail beyond what the schema provides, 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 (Edita) and resource (o texto de uma mensagem), plus the scope constraint 'enviada por esta conta' that limits edits to the caller's own messages. It does not name how it differs from close siblings like send_message, reply_message, or delete_message, so it falls short of full sibling differentiation.

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 offers no when-to-use context, no prerequisites, and no mention of alternative tools. The only hint of applicability is the ownership constraint, which is a scope limit rather than 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?

With annotations present the bar is lower, and the description adds real context: what 'accept' does (accepts a received request), what 'remove' does (removes friendship OR declines/cancels a pending request), and a mode restriction ('So em modo user'). It does not explain rate limits or return behavior, but the effect of each mutating action is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but well organized, one clause per action with the default behavior front-loaded. Every clause earns its place; no redundant filler.

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-output-schema tool with three actions and four params, the description covers all actions, the default, and the mode constraint. A note on what the raw JSON return contains is the only meaningful gap, but the action coverage is sufficient to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents type/action/format/userId including the userId pattern. The description reinforces userId's role in accept/remove and implies the type filter via 'recebidos/enviados/bloqueados', but 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?

The description states specific verbs and resources for each mode: 'list' returns friends/pending requests/blocked, 'accept' accepts a received request, 'remove' removes a friendship or declines/cancels a request. This is clear and actionable, though it does not explicitly name sibling tools to differentiate itself from the surrounding DM/message/channel tools.

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 maps each action to its outcome and flags the default ('list (padrao)'), plus a precondition ('So em modo user'). This gives clear context for when each action applies, but it never names alternatives or states when NOT to use 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 readOnlyHint=true and openWorldHint=true, so safety is covered. The description usefully discloses the shape of the response (type, name, topic, server, participants, parent, thread metadata), which is valuable since no output schema exists, but it says nothing about failure behavior for a bad/unknown id.

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: the verb comes first, followed by a compact enumeration of return fields. Nothing is wasted and nothing is 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?

With no output schema, the field enumeration carries real weight and covers the channel/DM/thread cases the agent needs. What remains missing is minor for a read-only tool: error behavior for missing ids and permission 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 coverage is 100%, so both parameters are already documented in the schema, including the text/json enum for format. The description only echoes that channelId may be a channel, DM or thread, adding no syntax or format detail beyond the schema. 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?

The description gives a specific verb+resource ("Devolve os dados de um canal, DM ou thread") and enumerates the returned fields, so an agent immediately knows it fetches details for a single channel-like entity. It implicitly contrasts with list_channels/list_threads by being a singular getter, 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 only implied: fetch one entity by id when you already have the id. There is no statement of when to prefer this over list_channels, read_messages, or get_message, and no preconditions or exclusions are 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 and openWorldHint, so the safety profile is covered. The description adds a genuine behavioral trait beyond the annotations: a fallback to searching around the id in user mode. That is useful, but it is terse and does not explain what the fallback returns or when it triggers.

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 purpose leads and the fallback qualifier follows. It is efficient, though the parenthetical caveat is dense and slightly cryptic.

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 read-only lookup with full schema coverage and no output schema, the description is adequate: it states the lookup and the fallback. It omits how the fallback result is shaped and gives no routing against near-duplicate siblings, leaving minor 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%, so channelId, messageId and the format enum are already documented in the schema. The description adds no parameter syntax or format detail, 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?

States a specific verb (busca) and resource (mensagem) plus the lookup key (id), and the word 'especifica' contrasts with the plural list/search siblings. It does not, however, explicitly name read_messages or search_messages as the alternatives, so differentiation is implied 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 gives no when-to-use guidance or exclusions relative to read_messages (plural, channel scan) or search_messages. The agent must infer from 'pelo id' that this is the single-message-by-id path, which is weak routing guidance given several overlapping siblings.

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, lowering the bar. The description still adds value by disclosing that the returned payload varies by context: public fields by default, bio and mutual servers 'em modo user', and nickname/roles/join date when guildId is supplied. It omits auth/rate-limit context, but the conditional data exposure is genuinely useful beyond 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?

Two dense sentences that lead with what data is returned and then layer the conditional variants. No filler, though the phrasing around 'modo user' is terse enough to be slightly ambiguous.

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 explaining returns, and it does list the principal fields per mode. It is nearly complete for a read tool, with only the exact shapes and 'modo user' semantics left somewhat implicit.

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 every parameter (format, userId, guildId) is documented in the schema, so the baseline is 3. The description reinforces guildId's effect on returned fields but adds no syntax or format detail 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+resource ('Dados publicos de um usuario') and enumerates the returned fields, so the agent knows exactly what is fetched. It does not explicitly differentiate from siblings, but no sibling reads user profile data, so the risk of confusion is low.

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 implies usage conditions by describing the guildId and 'modo user' variants, letting the agent infer when member data versus public data is returned. However, it never states when to prefer this tool over alternatives or any prerequisites, so guidance is only implicit.

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?

Beyond readOnlyHint/openWorldHint, the description discloses three useful traits: the caller's own messages are excluded, results are grouped per conversation, and IDs are ready to hand to reply_message. The one significant omission is that markRead advances cursors and acks on Discord—a side effect hidden in one schema field on an otherwise readOnly-annotated tool—and the text/json output modes are also unmentioned.

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 dense sentences, front-loaded with scope, then filtering caveat, then window semantics. Nothing repeatable or decorative; every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With eight optional parameters, no output schema, and only two annotation hints, the description does solid work: it defines the item set, the exclusion rule, the grouping, and the window behavior. It falls short on the markRead mutation and the format switch, which materially affect what an agent gets back and what side effects it triggers.

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 eight parameters are already documented, which sets the baseline at 3. The description reinforces the 'hours' fallback window and the implicit dms/mentions/watched filters, but adds no syntax or interaction detail the schema does not already contain.

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 ('Lista o que chegou e ainda nao foi tratado') and enumerates the four sources it aggregates: DMs, mentions, watched channels, and gateway events. That enumeration plus the 'grouped by conversation' output hint clearly separates it from siblings like read_messages or list_dms, which lack the unhandled-items framing.

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 'still unhandled' scoping tells the agent this is a triage-first tool rather than a raw history reader, and it names reply_message as the natural downstream step. It never explicitly says when to prefer read_messages or mark_read instead, so there is no exclusion guidance, but the usage context is unambiguous.

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 cover the safety/mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuine value beyond them: joining via API may return CAPTCHA_REQUIRED and require action in the official app. That operational caveat is not derivable from the annotations and is exactly the kind of context an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, each earning its place: purpose first, then the accept modifier, then the captcha caveat. Front-loaded with the primary behavior and free of filler.

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 tool with no output schema and only moderate complexity, the description names what the invite data contains (server, channel, members) and flags the CAPTCHA_REQUIRED failure mode. Slightly more detail on the accept-mode side effects or error surface would make it 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%, so the schema already documents code, accept, and format. The description reinforces the meaning of accept=true but adds no syntax or format detail 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?

Starts with a specific verb and resource ('Mostra os dados de um convite') and then states the conditional join mode. It is clear what the tool does, though it never differentiates itself from any sibling (e.g. list_guilds or join_thread) that an agent might 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 dual-mode behavior (show vs. join via accept=true) is conveyed, which gives implied guidance on how to invoke it. However there is no explicit when-to-use or when-not-to-use framing and no named alternative, so the agent must infer the selection logic.

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 and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond them: joining makes the caller appear as a participant and enables live events, and leave=true reverses the state (consistent with idempotence). It omits permissions/rate-limit detail, but adds meaningful value over 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?

Two compact sentences, front-loaded with the action and its inverse, followed by the rationale for joining. No filler 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 no-output-schema join/leave tool with annotations that cover safety, the description supplies the action, the inverse mode and the effect of joining. The format parameter's return shape is covered by the schema, so nothing critical 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%, so channelId, leave and format are all documented in the schema itself. The description only echoes the leave=true behavior already stated in the schema, so it adds little beyond the structured fields — 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 (join) and resource (thread or forum post), and notes the inverse leave=true mode. It does not explicitly name a sibling such as create_thread or watch_channel to differentiate, but the action is unambiguous.

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 second sentence gives implied usage context ('joining is necessary in some threads to appear as a participant and receive live events'), which helps the agent understand why it would be called. However, it names no alternative tool and states no when-not-to-use condition, so guidance remains inferred rather than explicit.

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: results are grouped by category and may include channels the caller cannot read, with read_messages returning FORBIDDEN on those. Pagination and result limits are not addressed, keeping it short of 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?

Two dense sentences with no filler: the first covers what is returned and how it is organized, the second covers the access caveat. Everything is front-loaded and every clause earns its place.

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 compensates by naming the returned fields and the grouping, and the annotation covers the read-only profile. The permission caveat is a valuable addition. Only minor gaps remain (no pagination/volume guidance for large guilds).

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 query, types, format, and guildId are already fully documented in the schema, including the enum for types and the text/json format switch. The description adds no syntax or format detail 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 (lists a server's channels) plus scope details (grouped by category) and the fields returned (id, type, topic, last message). It distinguishes behaviorally from read_messages but never names the natural alternatives for a single channel (get_channel) or threads (list_threads), so sibling differentiation is only partial.

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 it to enumerate a guild's channels, and the note that channels without access may be included steers expectations. However, there is no explicit statement of when to prefer this over get_channel, list_threads, or search_messages, and no stated prerequisites.

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 genuine context beyond the schema: result ordering (most recent to oldest), the data returned, and critically the 'So em modo user' authorization constraint. It does not mention rate limits or paging 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 dense sentence that front-loads verb, resource, ordering, and returned fields before closing with the mode constraint. Efficient with no filler, though the run-on structure slightly reduces scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-param, zero-required, read-only list tool with no output schema, the description covers the essentials: what is listed, ordering, key return fields, and the user-mode requirement. The main gap is the lack of disambiguation from the 'inbox' sibling.

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 schema already documents limit, query, format, and onlyUnread. The description only loosely parallels the schema by describing the unread concept ('se ha algo nao tratado') and ordering, which is adequate but adds little beyond the structured fields.

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 (Lista) and resource (conversas diretas / DMs e grupos), plus the ordering and the fields returned (channelId, participantes, ultima mensagem, nao tratado). Highly specific, though it never differentiates itself from the sibling 'inbox', which could plausibly overlap.

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?

Adds one real usage condition: 'So em modo user', which tells the agent this is unavailable outside user mode. However, it offers no guidance on when to prefer this over inbox, read_messages, or open_dm, so routing between the DM-related siblings is left 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds return-content detail (id, name, owner, counts 'when available'), which is real value given no output schema, but says nothing about pagination, auth requirements, or why counts may be absent.

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 compact sentence with the resource scope front-loaded and the returned fields trailing. Nothing is wasted, though it is terse enough that it could have afforded one clause of usage guidance.

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 what it returns and its scope; annotations cover the read-only nature and the schema covers parameters. Only optional behavioral extras (pagination, count availability) are 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%, so both the query filter and the text/json format enum are already fully documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does 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+resource: listing the servers the account belongs to, and even names the fields returned (id, nome, dono, contagens). It is clearly distinguishable from list_channels/list_dms, though it never explicitly contrasts itself with 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?

There is no when-to-use guidance, no prerequisites, and no mention of when to prefer a sibling like get_channel or list_channels. The scoping phrase 'em que a conta esta' implies context but gives the agent nothing actionable about selection.

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?

With readOnlyHint and openWorldHint already declaring the safety profile, the description adds genuine context beyond annotations: the default to active threads, the archived override, and the returned fields (id, name, author, message count, last activity), which matter because there is no output schema. Pagination behavior is left to the 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 dense sentences with zero waste: the first covers purpose, scope, and returned fields; the second covers the forum-thread subtlety and the follow-up tool. Information is front-loaded and nothing is 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?

No output schema exists, and the description compensates by naming the returned fields and the default/override behaviors. For a 5-parameter read-only listing tool this is nearly complete, with only pagination semantics 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 coverage is 100%, so the baseline is 3, but the description adds real meaning by clarifying that channelId can point at a forum thread as well as a text channel ("leia com read_messages channelId=<thread>") and by restating the archived toggle's effect. This goes beyond the raw schema descriptions.

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 ("Lista") and resource (threads/posts of a text channel or forum), and explicitly notes that forum posts ARE threads, which disambiguates the resource from siblings like list_channels. The default active vs archived=true scope makes the boundary clear without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives conditional usage for archived listing ("archived=true para arquivados") and routes the agent to the correct alternative for reading contents ("leia com read_messages channelId=<thread>"). It does not, however, state when to prefer this over list_channels or other listing tools, so it stops short of full when/when-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 cover the safety profile (readOnly=false, idempotent=true, destructive=false), and the description adds genuine behavioral context beyond that: it advances a local cursor, exits the inbox, and performs a Discord ack. It does not discuss permissions or return behavior, so it stops short of 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?

A single sentence front-loads the core action, then the side effects, then the usage condition. Every clause earns its place with no filler.

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 mutation tool whose annotations carry the safety profile and whose schema is fully described, the description supplies purpose, side effects, and usage trigger. No output schema is needed given the format parameter, so nothing an agent needs to invoke it 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%, so the schema fully documents channelId, messageId, and the format enum, including the default-to-latest behavior. The description restates the messageId default but adds no 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 a specific verb+resource+scope: marks a conversation as handled up to a message. It goes beyond the name by describing the concrete effects (advances the local cursor, leaves the inbox, acks on Discord), so an agent can distinguish it from the inbox/read_messages siblings without opening any 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?

'Use quando decidir nao responder' gives a clear decision condition that selects this tool over send_message/reply_message. It does not name explicit alternatives or exclusions, but the when-to-use context is unambiguous.

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, readOnlyHint=false. The description reinforces the non-destructive nature with 'Nao envia nada' and the idempotency with 'abre (ou reabre)', adding useful context beyond the structured flags. It doesn't mention auth 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 tight sentence that front-loads the action, then the return value, then the clarifying constraint. 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 simple two-parameter tool with full schema coverage and no output schema, the description covers purpose, non-effect, and the return value (channelId) that the agent needs downstream. 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 coverage is 100%, so both the userId pattern and the format enum are already fully documented in the schema. The description adds no further 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 (abre/reabre) and resource (conversa direta) and explicitly clarifies the negative scope with 'Nao envia nada', separating it from send_message. The agent knows exactly what it does and what it does not do.

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?

Explains the tool returns the channelId needed by read_messages/send_message, which clearly implies when to reach for it (before reading or sending in a DM). It lacks an explicit 'when not to use' or a named alternative for pre-existing channels, but the context is unambiguous.

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 description says markRead=true marks the conversation as read, which is a state mutation, while the annotations declare readOnlyHint=true. That is a direct contradiction and per the rubric scores 1.

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 dense sentences, front-loaded with the core purpose and followed by pagination and markRead behavior. No filler 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?

It covers ordering, pagination, and markRead semantics, but with no output schema it does not explain the shape of returned messages or permission expectations. For a seven-parameter read tool, that leaves a meaningful 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 the schema already documents all seven parameters. The description adds useful context about ordering and pagination by message id, but largely aligns with what the schema 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 and resource: reads messages from a channel, DM, or thread, with ordering detail. It does not explicitly differentiate itself from siblings such as get_message or search_messages, 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?

The description implies the tool is for reading messages and explains pagination parameters, but it gives no explicit guidance on when to use it instead of get_message, search_messages, or watch_channel, and no exclusions.

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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful provenance the annotations cannot convey: the data comes from protocolo.md or the PROTOCOLO variable. It remains silent on caching, freshness, or error behavior when the file is absent.

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 tightly packed sentences with no filler, and the routing instruction ("Leia antes de responder clientes") is placed last as a call to action. The mid-sentence enumeration of protocol contents is long but each item earns its place by telling the agent what to expect.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must convey what comes back; enumerating rules, prices, deadlines, and tone does that well, along with the two possible sources. It is complete enough to call correctly, though it omits behavior for the failure case where no protocolo.md exists.

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 enum parameter (format: text/json) is fully documented in the schema, so the baseline of 3 applies. The description never mentions the format option, adding no meaning beyond the schema. With only one well-documented parameter, this is acceptable but not additive.

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 ("Devolve") and a concrete resource ("protocolo de atendimento") and then enumerates its contents (regras, precos, prazos, tom, o que pode ou nao prometer). No sibling in the Discord-oriented list could be confused with it, so the boundary is clear 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?

"Leia antes de responder clientes" gives an explicit moment to invoke the tool, which is stronger than implied usage. It does not name alternatives or exclusions, but no sibling covers the same purpose, so that omission is minor.

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?

Goes beyond the annotations (readOnly=false, idempotent=false, destructive=false) by disclosing two side effects: the conversation is marked as handled, and replying twice to the same message is refused. It does not mention rate limits or error behavior, but the key mutation semantics are covered.

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 compact sentences with the core action, the parameter sourcing, and the side-effect constraints front-loaded; every sentence carries information an 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 mutation tool with rich annotations and a fully described 10-parameter schema but no output schema, the description covers the main behavioral traits and parameter sourcing. Return format is omitted, which is acceptable given no output schema is declared.

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 baseline is 3, and the description adds value by explaining the provenance of messageId (the value returned by inbox/read_messages), which the schema itself does not state.

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 (reply) and resource (a specific message), and clarifies the reply is sent with a reference to the original message, which distinguishes it from the sibling send_message. An agent can tell what this tool does 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?

Explicitly tells the agent where to source messageId (from inbox/read_messages) and states the duplicate-reply constraint. It does not name send_message as the alternative for non-reply posts or give an explicit when-not condition, keeping it below 5.

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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses that the tool only works in user mode and, valuably, that Discord's index may lag and can return SEARCH_INDEXING with retryAfterMs. This is genuine behavioral context an agent needs to handle retries, though return format/pagination behavior is left to the 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?

Three short sentences, front-loaded with the search semantics and scope before the mode constraint and the indexing caveat. No filler; each sentence carries distinct 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?

With ten fully documented parameters, readOnly/openWorld annotations, and no output schema, the description supplies the extra pieces an agent needs: the user-mode requirement and the SEARCH_INDEXING/retryAfterMs async caveat. Only the explicit alternative-tool routing 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%, so the schema already documents all ten parameters (has, before/after, limit, offset, format, content, authorId, guildId, channelId) in detail. The description only restates the guildId=server / channelId=DM distinction already present in the schema, 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?

The description states a specific verb (procura/search) and resource (mensagens/messages) plus the search dimensions (texto, autor, tipo de conteudo) and scope (server via guildId or DM via channelId). It is clearly a filtered search rather than a sequential read, distinguishing it from read_messages, though it does not name any 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 implied by the search-by-text/author/type framing and it adds a real prerequisite ('So em modo user'), but it never states when to prefer this over read_messages or get_message, nor any exclusions. Adequate but with a clear gap in 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 it is a non-idempotent, open-world mutation, and the description adds meaningful context beyond that: it marks the conversation as handled (a side effect), refuses duplicates, and enforces length and rate limits. This is solid disclosure of failure modes and side effects, though it doesn't explain what happens to the rate-limited message or the response shape.

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 purpose, then the reply variant, then side effects and constraints. Every sentence carries distinct information with no 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 10-param mutation tool with full schema coverage and annotations, the description covers purpose, the reply shortcut, the mark-as-read side effect, and the main rejection paths. Return behavior is left implicit, but no output schema exists and the format param partly covers it, making this nearly 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%, so the schema already documents all 10 parameters, including split, replyTo and format. The description restates the replyTo effect and the 2000-char/split boundary but adds no syntax or semantics 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?

Specific verb (Envia) + resource (mensagem) + scope (canal, DM ou thread). It also distinguishes itself from the sibling reply_message by stating that replyTo makes it a reply, so the agent can tell the two apart without opening either 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?

It explains the key routing condition: use replyTo to reply, which is equivalent to reply_message. It also lists rejection conditions (duplicates, >2000 chars without split, rate limiting), giving clear context. It doesn't explicitly say when to prefer a different sibling like open_dm first, so it falls short of a 5.

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 establish that this mutates state (readOnlyHint=false), is idempotent and non-destructive. The description adds genuinely new behavior: watched channels route all traffic to the inbox without requiring a mention, and the watch list is persisted. It does not discuss auth requirements or how removal affects existing inbox items.

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?

Four short clauses, each front-loading an action token followed by its effect, with the default flagged inline. 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 4-parameter tool with no output schema, the description covers the action semantics, the default mode and the persistence trait, which is enough to invoke it correctly. Minor gaps remain around error cases and whether watched channels persist across sessions.

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 goes further by spelling out the runtime effect of each action enum value and confirming the 'list' default. The note and format parameters are left entirely to the schema, which is acceptable given full 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?

The description names a concrete verb+resource ('watch channel') and breaks down exactly what add, remove and list do, including the notable effect that watched-channel traffic reaches the inbox even without a mention. It is clearly distinguishable from siblings like list_channels or inbox, though it never explicitly contrasts itself with 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?

It explains each action mode and marks 'list' as the default, which effectively tells the agent when to use which mode. There is no explicit when-not guidance or named alternative (e.g. mute or search_messages), so it falls short of a 5.

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