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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds useful semantics by explaining that the return is a set of observed identity pairings with a concrete example. Beyond that it discloses nothing about scope, pagination, or failure behavior, so the bar set by annotations is only modestly exceeded.

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 core statement is short and front-loaded, which is good, but the trailing transport cruft ('POST /api/kalagh/channels/aliases · gRPC GetPlatformAliases · socket "channels/aliases"') consumes the second half without helping an agent decide or invoke. Structure is acceptable but not clean.

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 carries the burden of conveying what comes back, and the pairing example partly does that. But the single parameter is unexplained and there is no usage context, leaving the definition only minimally complete for a channel-scoped read.

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 one required parameter, channelId, whose schema description coverage is 0%. The description never mentions the parameter or explains what channel it refers to, so it fails to compensate for the documentation gap. This is below the 3 baseline because coverage is low and the description adds nothing.

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 the resource ('identity pairings this channel observed') and gives a concrete example (WhatsApp LID ↔ phone JID), which helps an agent understand the payload. However, it is a noun phrase with no verb and gives no differentiation from nearby siblings like channels_get or channels_list. Purpose is inferable but not stated as an operation.

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 tool, what prerequisite state is needed, or which alternative to prefer. It is listed among many channel tools with no routing information at all.

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, and openWorldHint=true, so the safety profile is covered. The description adds one useful behavioral fact — that creation immediately returns a QR code/state — but says nothing about authentication, whether config state is persisted, or side effects like webhooks/logLevel. Adequate but not rich.

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 compact sentence front-loads the action and result. The transport parenthetical (REST route, gRPC method, socket event) is arguably noise for tool selection but is short and arguably useful for cross-referencing.

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 must carry the return contract, and 'first QR code / state' is only a partial hint — it doesn't explain the channel identifier or state shape. Combined with 8 undocumented parameters including a nested config object, the definition is incomplete for a creation tool.

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 0% across 8 parameters (title, id, config, logLevel, logWebhook, webhookUrl, raiseEvents, syncHistory, plus a nested config object). The description names none of them, so an agent has no idea what config, logLevel, or syncHistory do or what values are expected.

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 channel') and even discloses the primary return value ('its first QR code / state'). However, it never distinguishes a 'channel' from a 'chat', despite chats_create being a sibling, so an agent cannot tell the two apart from the description 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?

There is no when-to-use guidance, no prerequisites, and no mention of how this differs from chats_create or when to prefer channels_get/channels_request_qr instead. The agent gets no routing help.

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 readOnly=false, destructive=true, openWorld=true, and the description is consistent with them while adding real context: the deep-merge semantics, the fact the change reaches the platform, and the explicit expectation of user confirmation. That is useful detail beyond the flags, though it stops short of describing reversibility or what gets preserved.

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 purpose sentence is tight and front-loaded, which is good. The second sentence is generic boilerplate applicable to almost any destructive tool rather than specific to this operation, and the trailing parenthetical restates transport details that add little selection value.

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 mutation with no output schema, the description covers the safety posture (destructive, reaches others, confirm first) and the merge behavior that the annotations alone would not convey. What remains thin is identification of the channel id's format and the effect on unspecified fields, but the core calling requirements are present.

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 credentials parameter's merge behavior (objects merge, arrays/scalars replace) is already spelled out in the schema, so the description's 'deep-merge' phrasing repeats rather than extends it. The id parameter is undocumented in both places, and at 50% coverage the description does not compensate for that gap. 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: 'Deep-merge fields into a channel's stored credentials'. This clearly distinguishes the tool from a plain settings update, and the parenthetical names the underlying endpoint/gRPC method. It does not, however, explicitly contrast against channels_update or channels_create, so an agent must infer the boundary itself.

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 communicates a requirement before acting: say exactly what will happen and obtain the user's confirmation first, which is genuine procedural guidance for a destructive call. It does not, however, say when to prefer this over channels_update or other credential-adjacent siblings, so usage direction 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 destructiveHint=true and openWorldHint=true, so the safety bar is partially met. The description goes beyond them by disclosing cascade behavior ("everything that hangs off it") and external side effects ("reaches other people on the platform, deletes, or redirects data"). The phrasing of that side-effect clause is ambiguous about what actually happens on the wire.

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 cascade statement is front-loaded and useful, and the endpoint metadata is compressed. But the second sentence is subject-less and grammatically muddled ("Reaches other people on the platform, deletes, or redirects data"), making it cost more attention than it returns.

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 destructive tool, the description plus annotations cover the essentials: cascading scope, external effects, and a confirmation requirement. There is no output schema, and the description doesn't address error/partial-failure behavior on a cascade, which is the main residual 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 0% and the description says nothing about the single `id` parameter — not which channel identifier it is, whether aliases are accepted, or what format is required. The schema's example string is the only clue, so the description fails to compensate for the coverage gap.

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 and resource ("Delete a channel") and adds scope with "everything that hangs off it," which distinguishes it from a single-object delete. It does not, however, differentiate from sibling lifecycle tools like channels_terminate or channels_unload, which is a plausible confusion set.

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 does give a workflow directive — get explicit user confirmation before executing — which is valuable for a destructive tool. But it names no alternatives and no conditions distinguishing this from channels_terminate/channels_unload, so the agent must infer when deletion is the right call.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only transport plumbing (POST path, gRPC method, socket channel) and no behavioral context such as error handling, missing-channel behavior, or whether both lookup keys may be combined.

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?

Extremely terse and front-loaded: purpose first, transport mapping second. The endpoint/gRPC/socket detail is arguably marginal for an agent, but the whole thing is two lines 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 simple read tool with full schema coverage and annotations carrying the safety profile, this is nearly adequate. The key gap is the 'at least one of id/platformId' contract implied by 0 required parameters, which is left unexplained.

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 each parameter documented and exampled, so baseline is 3. The description reinforces the two lookup modes but adds no rule about precedence or mutual exclusivity, which matters given there are 0 required parameters.

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 resource (one channel) and the two lookup keys (row id or connected account id), which implicitly contrasts with channels_list. However, it never names a sibling tool or says 'retrieve' explicitly, so differentiation depends on the reader inferring it from 'One channel'.

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 alternatives such as channels_list, and no statement about which key should be preferred or what happens if both or neither id is supplied. The agent gets no routing help beyond the one-line purpose.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only transport trivia (POST path, gRPC method, socket name) that does not help the agent understand behavior such as paging defaults, ordering, or what a page contains. It contributes almost nothing 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?

It is short and does not waste words on marketing filler, but it is under-specified rather than concise. The parenthetical endpoint metadata is arguably the bulk of the text and is not the most useful content for an agent.

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, two undocumented parameters, and only a vague "page of channels" return statement, the description is not complete enough for an agent to call this correctly with meaningful paging. A list tool with pagination should at minimum describe page/limit semantics and the shape of the returned page.

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 0% and the two parameters (page, limit) carry only example values. The phrase "a page of channels" hints at pagination but supplies no defaults, no maximum limit, no ordering, and no meaning for what page numbering starts at, so the description fails to compensate for the undocumented 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?

"A page of channels" essentially restates the tool name channels_list, adding only the notion of paging. It gives no verb of intent (list vs. search vs. enumerate) and does not distinguish this tool from siblings like channels_get, channels_aliases, or channels_list's own filtering behavior.

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 channels_get (single channel), channels_aliases, or any other channel tool, and no prerequisites or constraints are stated. The agent must infer usage entirely from the 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=false, destructiveHint=false and openWorldHint=true, so the safety profile is partly covered. The word 'fresh' hints that a new code is generated (possibly invalidating a prior one), but the description does not state whether existing QR codes are revoked, how long the code is valid, or any auth requirements.

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 stating what is returned, with the endpoint triple in a parenthetical. The transport details (POST path, gRPC method, socket name) are useful for a multi-protocol server but are somewhat redundant padding; otherwise efficient.

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 parameter, no output schema and partial annotation coverage, the description does state the return artifact (a QR code) but omits side effects on existing codes, validity/lifetime, and how the code is delivered. Adequate but with clear gaps for a state-mutating endpoint.

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 0% for the single required parameter, so the description carries the burden. 'For a channel awaiting pairing' weakly implies that id is the channel identifier, but neither the meaning nor format of id is clarified beyond the schema's example value.

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 the concrete resource (a login QR code) and the qualifying state (a channel awaiting pairing), which distinguishes it from siblings like channels_get or channels_credentials_patch. It falls short of an explicit verb such as 'request/regenerate', but the intent 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 phrase 'awaiting pairing' implies the condition under which this tool applies, giving implied rather than explicit usage guidance. It never states when to prefer this over channels_credentials_patch or channels_restart, nor what to do once the channel is paired.

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=false and openWorldHint=true, so safety and network reach are covered structurally. The description's added value is 'keeping its pairing', which is genuinely useful behavioral context, but it omits what the restart actually does to the live session (downtime, dropped messages, re-auth) and whether the operation is synchronous.

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?

Front-loaded with the meaningful clause and kept to a single tight sentence; the trailing transport triple (POST path, gRPC method, socket name) is marginally useful metadata but borders on 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?

With no output schema and annotations covering only the safety profile, the description should say more about the operation's observable behavior — duration, whether it is async, and what state the channel returns to. It is adequate for identifying the tool but thin for invoking a session-affecting operation 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 description coverage is 0% for the single required 'id' parameter; the schema provides only an example value and no description. The description says nothing about the parameter at all, so it fails to compensate for the coverage gap, though the parameter's meaning (channel id) is weakly inferable from context.

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 ('Reconnect the channel's session') and adds the differentiating property 'keeping its pairing', which separates it conceptually from channels_terminate/channels_unload. It stops short of naming a sibling or explaining when a reconnect is preferred over a terminate, so it lands at clear-but-not-sibling-aware.

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 when-to-use or when-not-to-use statement. The phrase 'keeping its pairing' only implies a contrast with the terminate/unload siblings, leaving the agent to infer the selection condition rather than being told 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 destructiveHint=true and openWorldHint=true, so the danger profile is known, and the description goes beyond them by (a) naming the concrete effect — logout with the pairing dropped — and (b) imposing a mandatory user-confirmation workflow before invocation. It still does not say whether the action is reversible or how to re-pair afterwards.

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?

Short and front-loaded: the effect is in the first clause, the safety instruction second, transport details bracketed last. The middle sentence is slightly generic boilerplate ("Reaches other people... deletes, or redirects data") but costs little.

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 destructive mutation with no output schema, the description adequately covers effect and the confirmation requirement but omits the parameter's meaning, reversibility, and any post-termination state (e.g., whether the channel must be re-created).

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 one required parameter, `id`, with 0% schema description coverage — only an opaque example string. The description never says what the id identifies (channel id vs. session id) or how to obtain it, so it does not compensate for the schema's silence.

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 concrete verb and resource ("Log the channel out of the platform") plus the key consequence ("pairing is dropped"), so an agent knows this is a logout/teardown action rather than a rename or restart. It does not differentiate itself from the close siblings channels_unload, channels_delete, or channels_restart, which matters given how similar those names are.

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

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

It gives one real usage instruction: state exactly what will happen and obtain the user's confirmation before calling. That is a prerequisite, not a when-to-use-vs-alternatives rule; nothing tells the agent when to pick terminate rather than unload, delete, or restart.

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=false and readOnlyHint=false, so the safety profile is known. The description goes beyond them by clarifying the scope of the mutation: only the in-memory session is dropped and the login/session is preserved, which explains why the operation is non-destructive and suggests it is recoverable. It adds no auth, rate-limit, or idempotency context.

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 compact sentence with the effect front-loaded and transport metadata tucked into parentheses as secondary detail. No waste, though the parenthetical triple-endpoint listing is more implementation trivia than agent-facing 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 one-parameter mutation with no output schema, the description covers the effect and the key caveat but leaves the `id` semantics and prerequisite channel state (must it be connected? what happens on repeat calls?) unaddressed. Adequate but not sufficient for confident invocation.

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 0% and the single `id` parameter is documented only by an example value. The description does not say whether `id` is a channel id, session id, or alias, nor what its format is, so it fails to compensate for the schema gap on the one parameter that matters.

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 ('Drop the channel's session from memory') and adds the crucial qualifier 'without logging out', which distinguishes it semantically from channels_terminate and channels_delete. It never names those siblings, so an agent still has to infer the boundary rather than being told 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?

'Without logging out' implies the usage condition (free in-memory state while keeping the session alive), which is a meaningful hint. However, no sibling is named and there is no explicit when-to-use / when-not-to-use guidance versus channels_terminate, channels_restart, or channels_delete — arguably the most important decision for this 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 and openWorldHint=true, so the safety profile is partly covered. The description adds a genuinely useful instruction to confirm before proceeding, but the side-effect phrasing ('reaches other people on the platform, deletes, or redirects data') is generic and does not tie specific fields to specific 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?

The action is front-loaded and the description is short, but the middle sentence is a run-on whose generic side-effect list reads oddly for a channel-settings update, and the endpoint/gRPC/socket trailer is mechanical noise for the agent.

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 no output schema, the description covers the settings touched and the confirmation requirement, but it omits whether unmentioned settings are preserved or cleared (partial vs. full update) and gives no sense of the response.

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 0% across 9 parameters, so the description carries the full burden. It names setting groups that loosely map to title, webhookUrl/logWebhook, raiseEvents and logLevel, but leaves config, metadata, syncHistory and the required id undocumented with no format or effect details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ('Change a channel') and enumerates the affected settings (title, webhook, event, logging), which distinguishes it from siblings like channels_create and channels_delete. It is clear, though it does not explicitly contrast itself against neighboring 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?

Usage is implied by the verb and by the safety instruction to confirm with the user first, but there is no explicit when-to-use framing nor any named alternative for related operations (e.g., channels_credentials_patch vs. this). The agent must infer scope 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=false, destructiveHint=true, and openWorldHint=true, so the mutation and external-visibility profile is covered. The description adds a useful confirmation requirement, but the 'deletes, or redirects data' clause is inapplicable boilerplate for an additive operation and adds no real 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?

The core action is front-loaded in the first sentence, and the endpoint/gRPC/socket footer is compact. The second sentence is generic warning boilerplate rather than task-specific guidance, so it earns its place less clearly.

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 nothing is said about the result of the mutation, and parameter meaning is left entirely to the schema's sparse examples. Annotations cover the safety profile, so the definition is minimally viable but leaves an agent guessing about ID semantics and outcome.

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 0% across three required parameters (chatId, channelId, participantId) that carry only example values. The description says nothing about what these IDs are, their format, or the chatId/channelId relationship, so it fails to compensate for the coverage gap.

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 ('Add a participant to a chat'), which is unambiguous and implicitly contrasts with the sibling chats_remove_participant. It does not explicitly name the inverse sibling or scope, 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?

Provides a prerequisite ('get the user's confirmation first') for an action that reaches other people, but the warning reads as generic boilerplate ('deletes, or redirects data') that does not apply to adding a participant. No alternatives or when-not-to-use conditions are given relative to chats_remove_participant or chats_get_participants.

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 and openWorldHint=true, so the safety profile is covered. The description adds only transport plumbing (REST path, gRPC method, socket event) and says nothing about what archiving actually does to the chat, whether it is reversible, or whether it affects messages/notifications.

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 line with the verb+resource first, which is good structure. The parenthetical transport metadata is low-value for an agent that just invokes the tool, but it costs little.

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 no output schema and no annotations describing side effects, the definition should state reversibility, scope of effect, and any required state. None of that is present, leaving the agent with only a name and two opaque IDs.

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 0% and the description mentions no parameters at all, so it does not compensate for the gap. The parameter names chatId and channelId with example values in the schema make the intent inferable, but the definition adds zero meaning 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 ('Archive a chat'), which is unambiguous and clearly the inverse of the sibling chats_unarchive. It does not explicitly name the sibling or scope the operation, so it stops short of the 5-level 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?

There is no when-to-use guidance, no prerequisites, and no mention of the complementary chats_unarchive or the alternative of muting/pinning. The agent must infer entirely from the tool name that this is the archival action.

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=true and openWorldHint=true. The description adds a confirmation requirement and the fact that it 'reaches other people on the platform', which is useful, but the 'deletes, or redirects data' clause is generic boilerplate that never states what is actually affected by creating a chat.

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 core action is front-loaded, but the middle sentence is generic policy boilerplate that does not earn its place, and the trailing endpoint/gRPC/socket parenthetical is debug metadata rather than agent-facing 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 destructive, open-world mutation with no output schema and 0% parameter coverage, the description should explain what is created, in which channel, and with whom. None of that is covered, leaving significant gaps for a tool with a required channelId.

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 0% and the description mentions none of the three parameters (name, channelId, participants). Only the vague term 'group' hints at participants; the required channelId and name are left entirely to the schema's bare examples.

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 ('Create a chat') and clarifies that it is a group where the platform supports them. However, it does not distinguish itself from the many sibling tools (e.g. channels_create, chats_update), so an agent gets a clear action but no 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 only guidance is a generic confirmation warning ('say exactly what will happen and get the user's confirmation first'), which is a policy reminder rather than when-to-use context. No conditions, prerequisites, or alternatives (e.g. channels_create) are named.

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, readOnlyHint=false and openWorldHint=true, so the safety profile is known. The description adds real beyond-annotation context: that this is a SOFT delete and that it 'reaches other people on the platform, deletes, or redirects data', which is exactly the kind of consequence an agent needs. It stops short of saying whether the chat is recoverable or what happens to its messages.

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?

Front-loads the verb+resource, which is good, but the middle sentence reads as generic injected caution text rather than tool-specific instruction, and the endpoint/path parenthetical is metadata of limited use to an agent. Small overall, but not every sentence 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?

For a destructive mutation with no output schema, the definition covers the safety framing and side effects, and annotations cover the rest. It omits permissions/auth requirements, recoverability, and the fate of nested messages, which an agent deciding to call a delete would benefit from.

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?

Only one parameter exists (chatId) and schema description coverage is 0%, so the description carries the full burden for it. The description says nothing about chatId's format or meaning; the only hint is the example value inside the schema. With a required, undocumented parameter this is a clear gap.

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 ('Soft-delete a chat'), and the 'Soft-' qualifier usefully distinguishes it from a hard delete or from chats_archive. It does not explicitly name a sibling to route against, 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?

It gives a precondition (warn the user and get confirmation first), which is genuine usage guidance, but never says when to prefer this over siblings like chats_archive or chats_update, nor when not to use it. Usage is implied rather than laid 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=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the transport surface (REST path, gRPC method, socket event) and the two-key lookup model, but says nothing about not-found behavior or result shape, so it only modestly exceeds 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 front-loads the purpose before the parenthetical transport metadata. Nothing is padded, though the protocol parenthetical is arguably noise for an agent selecting the tool.

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?

A read-only 3-parameter getter with full schema coverage and safety annotations does not need much more, but with no output schema the description should hint at what a chat record contains or what is returned on a miss. As written it is adequate but leaves 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 coverage is 100%, so the id fields are already documented, including 'Required with platformId' on channelId. The description restates the same relationship ('by row id, or by platform id within a channel') without adding format or fallback semantics, so this is the 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 ('One chat') and resource, plus the two addressing modes (row id, or platform id within a channel). It is distinguishable from chats_list/chats_search in that it fetches a single chat, but it never names a sibling to explicitly frame the contrast.

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. The agent is left to infer that this is the single-record getter versus chats_search or chats_list, and there is no note on what to do if the chat is not found.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds meaningful behavioral context beyond that: the file is saved locally with its path returned, images are rendered, and the byte-delivery path differs between gRPC (in-band) and REST/socket (fetched from provider storage). It stops short of stating what happens when the chat has no avatar or what error/return shape to expect.

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 compact, but the first sentence is awkwardly front-loaded ('described') while the actually decisive information (local file path returned, transport-dependent retrieval) comes later. The parenthetical endpoint/transport note is reference metadata rather than agent-facing 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?

With no output schema, the description does partially discharge the return-value burden by explaining that a local path is returned and images are shown. But it omits the format of that path, what happens on failure or missing avatar, and any pagination/size concerns, leaving gaps for a retrieval tool with two required and undocumented parameters.

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 0%, so the description carries the full burden for chatId and channelId — yet it says nothing about either parameter, not even the chatId/channelId pairing requirement. Both are inferable only from parameter names and example UUIDs.

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 — retrieving a chat's avatar — and the endpoint line (POST /api/kalagh/chats/get-avatar · gRPC GetChatAvatar) pins it down, distinguishing it from contacts_get_avatar. However, the opening phrase 'A chat's avatar, described' is ambiguous phrasing that only becomes clear after reading the rest.

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 tool versus siblings like chats_get or contacts_get_avatar, nor any prerequisite (e.g. must the chat exist, does it need an avatar to be set). The agent gets transport mechanics but no selection criteria.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond the word 'stored', which vaguely hints at cached vs. live data but is never clarified; the POST/gRPC/socket triad is transport trivia rather than agent-relevant behavior. No return shape, error conditions, or permission requirements are 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?

A single short sentence, which is appropriately sized and front-loaded. However, the parenthetical endpoint list is noise that does not help an agent decide or call the tool, consuming roughly half the text.

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, so the description should explain what the participant list contains (fields, ordering, pagination) and any failure modes; it does none of that. For a read tool on a shared chat resource, an agent cannot predict the response or handle empty/error cases.

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 required parameter (chatId) with 0% schema description coverage, so the description carries the full burden of explaining it — and it says nothing about it. The schema's example format gives a weak hint about the expected ID shape, but the description neither compensates nor adds meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The phrase 'The stored participants of a chat' names the resource and the scope, so an agent can tell it returns participant data for one chat. But there is no verb, and 'stored' is never explained, so it does not clearly distinguish itself from siblings like chats_get or contacts_list. Purpose 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?

No when-to-use guidance, no prerequisites, no mention of alternatives such as chats_get (chat metadata) or chats_add_participant / chats_remove_participant (mutations of the same resource). The description only identifies the endpoint, leaving selection entirely 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered without description help. The description adds only transport plumbing (POST path, gRPC method, socket event), which is not behavioral context a caller needs. It says nothing about ordering, default page size, or what happens past the last page.

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 line with no filler, and the resource statement comes first. The parenthetical transport dump is arguably noise for a caller, and the mid-string line break is awkward, but it is efficient overall.

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, no parameter documentation, and 0% schema description coverage, the description should carry more weight. It omits the return shape, pagination semantics, and defaults, leaving an agent unable to call this confidently beyond passing a channelId.

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 0% and the description never mentions page, limit, or channelId. The word 'page' faintly implies pagination, but the agent gets no default limit, no maximum, and no indication that channelId is the mandatory identifier versus an optional scope. The description fails to compensate for the coverage gap.

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 fragment 'A page of a channel's chats' names the resource and implies listing, but supplies no verb and does not distinguish this tool from close siblings such as chats_search, chats_sync, or chats_get. It also does not clarify how it differs from channels_list, which lists a different entity. An agent can infer the gist but must guess at the exact scope.

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 at all: no statement about choosing this over chats_search (filtered lookup) or chats_sync (delta sync). No prerequisites or context are given. The description is purely informational about the resource.

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=true, openWorldHint=true, so the safety profile is covered structurally. The description adds that the action reaches other people and should be confirmed first, but its wording ("deletes, or redirects data") is generic boilerplate that does not accurately describe what marking a chat as read actually does.

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?

Purpose is front-loaded in the first line, which is good, but the middle sentence is unscoped boilerplate that is not specific to this tool, and the parenthetical endpoint/gRPC/socket triple is developer metadata of marginal value to an agent selecting a tool.

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 mutation with annotations covering destructiveness and openness and no output schema, the core is adequate. The missing pieces are parameter meaning and a clear statement of the actual side effect (read receipts vs. data change), which the boilerplate warning does not supply.

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 0% and the description supplies no meaning for chatId or channelId beyond the schema's example values. Relying on self-explanatory names is a real gap when two required identifiers must be supplied correctly.

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 ("Mark a whole chat as read"), and the scope word "whole chat" implicitly separates it from the sibling messages_mark_as_read. It does not explicitly name that sibling, so it falls just 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 an actionable instruction ("say exactly what will happen and get the user's confirmation first") and a hint that the action is visible to others, but no explicit when-to-use/when-not or routing to alternatives like messages_mark_as_read. Usage is implied through a generic safety rule rather than stated.

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-destructive, open-world mutation, so the safety profile is partly covered. The description adds only transport plumbing (POST endpoint, gRPC method, socket event) and says nothing about effect scope: whether muting is permanent, what notifications it suppresses, idempotency, or required permissions.

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 the verb first, which is good. The parenthetical transport triple arguably adds little for an agent choosing a tool, but it is compact and not 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 mutation tool with no output schema, two undocumented required parameters, and no stated side effects or permissions, the description leaves real gaps. An agent cannot tell what state change results or what to expect on failure.

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 0% — chatId and channelId carry only opaque example IDs and no descriptions. The description supplies zero compensating meaning about these two required parameters, so the agent must guess at their format and 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?

The description states a clear verb+resource: 'Mute a chat'. That is unambiguous for an agent. However, it offers no differentiation from the very similar sibling chats_unmute (or chats_archive / chats_pin), 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 mute versus unmute, archive, or pin, nor any precondition (e.g. must the agent be a participant?). The agent must infer usage entirely from the 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=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only transport metadata (POST path, gRPC method, socket name) and says nothing behavioral, such as idempotency, whether pinning an already-pinned chat errors, or where the pinned chat appears.

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 line with the action stated first. The parenthetical transport details are compact, though arguably incidental to tool selection.

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 no output schema and undocumented parameters, the description is too thin: it never explains the effect of pinning, ordering semantics, or failure modes, leaving the agent to guess at 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?

Schema description coverage is 0%: both required parameters (chatId, channelId) carry only example values and no meaning. The description adds nothing about what either identifier refers to, so it fails to compensate for the coverage gap.

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 ('Pin a chat'), which is unambiguous on its own. It does not explicitly distinguish itself from the sibling chats_unpin, but the verb itself makes the contrast obvious to an agent.

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 the chats_unpin alternative. An agent must infer the use case entirely from the 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 destructiveHint=true, openWorldHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds that the action is visible to other people and requires user confirmation, which is useful, but it never says whether the removal is permanent, what happens to the participant's message history, or whether they can be re-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?

The purpose is correctly front-loaded in a single short clause, and the trailing endpoint line (POST route, gRPC method, socket event) is compact and useful for tracing. The middle line is template hedging that implies this tool may delete or redirect data, which is noise for a participant-removal operation.

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, open-world mutation with no output schema and three undocumented identifiers, the description omits the outcomes an agent most needs: permanence of the removal, effect on the participant's existing messages, and error conditions such as a non-member participantId. The endpoint metadata is helpful but does not close those 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 0% for three required parameters (chatId, channelId, participantId), and the description says nothing about any of them — not even the relationship between channelId and chatId, which is genuinely ambiguous here. The schema's bare examples carry all the meaning, so the description fails to compensate for the coverage gap.

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 opening line gives a specific verb+resource ('Remove a participant from a chat') that is immediately distinguishable from the inverse sibling chats_add_participant and from chats_delete (which removes the chat itself). It does not explicitly name an 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?

The second line supplies one usable precondition — confirm with the user before acting — which is real guidance for a destructive operation. However it is generic boilerplate hedged across three possible effects ('reaches other people... deletes, or redirects data') and gives no when-to-use boundary against chats_delete or chats_update.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds only transport trivia (POST route, gRPC method, socket channel); it says nothing about matching semantics (prefix vs substring), whether results are scoped to the given channel only, or how 'limit' affects pagination.

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 definition is a single compact line with the core verb+resource front-loaded. The endpoint/gRPC/socket parenthetical is mostly noise for tool selection, but it is short and does not obscure the primary statement.

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 should indicate what comes back (chat objects, ids, ordering) and how limit bounds the result set; it does neither. For a search tool with an unconstrained query parameter, this leaves the agent guessing at both input and output 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?

Schema description coverage is 0% for three parameters, so the description must carry the burden. It partially maps 'a channel's' to channelId and 'by name' to query, but gives no meaning or default for limit, which is entirely undocumented in both places.

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 and resource ('Search a channel's chats by name') plus the underlying endpoints, so the action is unambiguous. It does not, however, distinguish itself from nearby siblings such as messages_search or contacts_search, which also perform searches over different resources.

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 and no mention of alternatives. The phrase 'by name' weakly implies a name-matching search, but nothing tells an agent why it would pick chats_search over chats_list or messages_search.

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, and openWorldHint=true, so the safety profile is covered. The description adds only transport plumbing (REST path, gRPC method, socket event) and says nothing about whether syncing merges, overwrites, or deduplicates existing chats, or how expensive/rate-limited it is.

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 parenthetical endpoint/gRPC/socket metadata is arguably noise for an invoking agent but is compact and does not obscure the main clause.

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-style import with no output schema, the description omits the things an agent most needs: what 'import' does to existing local chats, whether it is idempotent, and what the result contains. Annotations cover only the coarse safety profile, so the definition is under-specified for the operation's risk.

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?

Only one parameter exists and schema description coverage is 0%, so the description must carry the burden. 'For a channel' loosely signals that channelId identifies the target, but it adds no format, validity, or semantics beyond that, leaving the single input essentially undocumented outside of an example value.

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 verb ('Import') and resource ('the platform's chat list for a channel') are specific, so the agent knows this pulls chat data into the local store. It does not, however, distinguish itself from the many adjacent siblings such as chats_list, chats_get, or chats_search, which an agent could easily confuse with 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?

There is no statement of when to call this rather than chats_list or chats_get, nor any prerequisite (e.g. a loaded/connected channel). The tool name implies a sync/refresh operation but the description never says when syncing is warranted.

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 and openWorldHint=true, so the safety profile is covered structurally. The description adds only transport-level endpoint metadata (POST path, gRPC method, socket event) and says nothing about idempotency, permissions, or whether unarchiving an already-active chat errors.

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?

Extremely short and front-loaded with the action. The bracketed endpoint mappings are marginally useful for debugging but are not what an agent needs to select or invoke the tool.

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 state-toggle mutation with two undocumented required identifiers and no output schema, the definition should at minimum identify what those IDs are and what state change results. It omits all of that, and no annotations compensate.

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 0%: both required parameters (chatId, channelId) carry only example values, no descriptions. The description provides no parameter meaning whatsoever, leaving the agent to guess what a chatId or channelId must reference.

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 ('Unarchive a chat') that an agent can distinguish from chats_archive. It stops short of explicit sibling differentiation (e.g. no note that this is the inverse of chats_archive), but the purpose 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?

No when-to-use, prerequisites, or conditions are given. The description is a bare verb phrase plus endpoint metadata; the agent must infer that this is called on a currently-archived chat.

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 and openWorldHint=true, so the safety profile is covered by structured data. The description adds the backend dispatch details (POST /api/kalagh/chats/unmute, gRPC UnmuteChat, socket event) but says nothing about auth requirements, idempotency, or side effects on notification state.

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 definition is one short, front-loaded statement with the action first and the transport details parenthetically appended. Nothing is padded, though the transport triple is marginally useful at best.

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 no output schema and 0% parameter documentation, the description should at least confirm the inverse relationship with chats_mute and the state it changes. It omits this, so an agent must reconstruct the semantics from the name and sibling list.

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 0% and the description supplies no meaning for chatId or channelId, leaving two required identifiers documented only by example values. It fails to compensate for the coverage gap, so an agent gets no help understanding which identifier scope is required.

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 ("Unmute a chat") and supplements it with the transport mappings (HTTP path, gRPC method, socket event), so the operation is unambiguous. It does not, however, explicitly relate itself to its inverse sibling chats_mute, leaving the agent to infer the pairing from names 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?

There is no guidance on when to use this tool versus chats_mute, whether the chat must currently be muted, or any preconditions. The only context given is transport plumbing, which does not help an agent choose between tools.

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, and openWorldHint=true, so the safety profile is covered by structured data. The description adds only transport plumbing (POST path, gRPC method, socket event) and says nothing agent-relevant such as idempotency or behavior when the chat is not pinned.

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 short front-loaded sentence plus a brief transport parenthetical; there is no filler and the core action leads. The endpoint/gRPC/socket detail is arguably noise for an agent but is kept compact.

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 two undocumented required parameters and no output schema, the description should say more about prerequisites, idempotency, or failure modes. Annotations cover safety only, leaving the operational picture thin.

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 0% and neither chatId nor channelId is explained in the description; only example values exist in the schema. The names and examples are largely self-explanatory, but the description contributes nothing to distinguishing the two identifiers or their scope.

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 ('Unpin a chat'), which clearly distinguishes it from its sibling chats_pin. It does not, however, state scope or context (e.g., that it operates on a chat within a channel), so it is clear but minimally differentiated.

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 exclusions, and no mention of the natural alternative (chats_pin) or of preconditions such as the chat actually being pinned. 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 destructiveHint=true and openWorldHint=true, so the mutation risk is structured. The description adds one genuinely useful fact — that the change 'reaches other people on the platform' — but the 'deletes, or redirects data' clause is generic boilerplate that does not describe what this rename actually affects or whether it needs elevated permissions.

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 purpose is front-loaded in three words and the endpoint metadata line is compact. However, the middle warning sentence is boilerplate that is largely inapplicable to a rename and dilutes the useful 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?

With annotations covering the safety profile and no output schema to explain, the main remaining burden is parameter meaning and usage context — both of which are thin. An agent would still need to infer who can rename, whether it applies to group chats, and what the required IDs reference.

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 0% and the description only implies the 'name' parameter via the word 'Rename'. It says nothing about the required chatId and channelId, that 'name' is optional, or the accepted value format, leaving two required identifiers undocumented.

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 opening 'Rename a chat' gives a specific verb and resource, which cleanly separates this tool from chats_create, chats_delete, and chats_get in the sibling list. It does not, however, explicitly contrast itself with any alternative or state the scope of the rename (e.g., group vs direct chat).

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 choose this over sibling update tools (contacts_update, messages_update, channels_update) or what preconditions apply. The 'get the user's confirmation first' line is a generic safety instruction rather than tool-selection 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 destructiveHint=true and openWorldHint=true, and the description earns credit by adding context beyond them: it warns that the action 'reaches other people on the platform, deletes, or redirects data' and requires explicit user confirmation. It does not describe reversibility or whether unblocking restores the relationship, but the added confirmation requirement is genuinely useful 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?

Front-loaded with the purpose, followed by the confirmation instruction and an endpoint/protocol footer. Three compact lines with little waste, though the transport metadata (POST/gRPC/socket) is arguably more for the caller than for tool selection.

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, open-world mutation the safety context is decently covered by annotations plus the confirmation instruction, and no output schema exists to explain. However, the total absence of parameter meaning for a 2-param required schema leaves a real 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 0% and the description says nothing about channelId or contactId, nor which channel semantics apply. For a 2-parameter tool the description fails to compensate for the schema gap, leaving both parameters documented only by their example values.

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 ('Block') and resource ('a contact on the platform'), which cleanly separates it from the sibling contacts_unblock. It does not explicitly name that sibling, so it stops short of the 5 anchor, 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 description adds a confirmation instruction ('say exactly what will happen and get the user's confirmation first') that guides invocation behavior, but it gives no when-to-use guidance relative to alternatives such as contacts_delete or contacts_update_status. Usage is implied rather than specified.

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 and openWorldHint=true, so the safety profile is covered by structured data rather than the text. The description adds only transport trivia (POST path, gRPC method, socket event) and says nothing about duplicate handling, phone normalization, required channel state, or what happens on conflict.

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 stating the action and its inputs, followed by a compact parenthetical of transport identifiers. Nothing is padded, though the transport parenthetical is arguably noise for an agent deciding whether to call the tool.

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 write tool with no output schema and zero schema-level parameter documentation, the description leaves the agent without ductive information about required channel context, duplicate behavior, or the response shape. It is not misleading, but it is thin for the tool's 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 description coverage is 0% across three required parameters, so the description must carry the load. It names name and phone but completely ignores channelId, the most opaque required field, and adds no format or constraint detail beyond the schema's examples.

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 ('Create a contact') that clearly separates it from siblings such as contacts_update, contacts_delete, and contacts_get. It also names the two salient inputs (name, phone), though it omits the equally required channelId, so the scope is slightly understated.

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 over contacts_update/contacts_sync, no preconditions (e.g. does the channel need to be connected?), and no exclusions. The only guidance is the implicit 'create' 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 destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful nuance — that the delete is "soft" (implying recoverability) — but does not explain what soft-delete concretely means, whether data is recoverable, or what happens to the contact thereafter.

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 lead phrase is well front-loaded, but the middle sentence is generic template boilerplate that does not earn its place, and the endpoint/gRPC/socket metadata is tertiary detail appended at the end.

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 tool with annotations carrying the destructive/open-world profile and no output schema, the description is adequate but not complete: it leaves the meaning of "soft-delete" and the contactId semantics undefined.

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 0% for the single required contactId, and the description adds nothing about it. The parameter name is largely self-explanatory, but the description does not compensate for the total absence of schema-level documentation.

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 ("Soft-delete a contact") and the qualifier "soft" usefully distinguishes it from a hard delete and from siblings like contacts_block or contacts_update. It does not explicitly name an alternative 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?

The only guidance is generic boilerplate ("Reaches other people... get the user's confirmation first") that reads like framework template text rather than tool-specific when-to-use advice. It never says when to use contacts_delete instead of contacts_block, contacts_update_status, or messages_delete.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds transport surface (HTTP path, gRPC method, socket event), which is routing detail rather than behavioral disclosure; it says nothing about not-found/error behavior or whether lookups are scoped to the caller's channel set.

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; the lookup modes come first and the parenthetical is compact. The transport metadata is arguably noise for selection but is not 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?

There is no output schema, so the description should carry more of the return-shape burden, but it says nothing about the contact object returned or the response on a missing contact. For a 3-param lookup tool with zero required parameters and optional-identifier ambiguity, this is adequate but leaves real 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 both identifiers and the 'Required with platformId' constraint on channelId are already documented. The description restates the two lookup modes without adding format, casing, or precedence rules (e.g. which wins if both contactId and platformId are passed).

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 (one contact), and the scope word 'One' implicitly separates it from contacts_list and contacts_search in the sibling set. It does not name a sibling explicitly, 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 explains the two lookup routes (row id, or platform id within a channel), which is useful for choosing which identifier to supply, but it never states when to prefer contacts_get over contacts_search or contacts_list, nor what happens on a miss.

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, destructiveHint=false, and openWorldHint. The description adds real behavioral detail beyond that: the file is saved locally and its path returned, images are also shown, and gRPC returns bytes in-band while REST/socket fetches them from provider storage. That transport-dependent return behavior is genuinely useful and not derivable from 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?

The resource is front-loaded, but the first sentence is a semicolon-joined fragment mixing the noun phrase with an HTTP path, and the transport sentence is dense and hard to parse. Nothing is egregiously wasteful, but the structure is muddled rather than crisp.

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, but the description does cover the return shape (local file path, image display) and transport differences. It omits failure behavior, e.g. what is returned when a contact has no avatar. Adequate but with clear 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 0%, so the description carries the full burden for two required parameters (channelId, contactId). It hints at the contact via 'a contact's avatar' but says nothing about what channelId identifies, how the two relate, or the expected ID format beyond the schema examples. Compensation for the coverage gap is minimal.

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 opening clause 'A contact's avatar, described' is a noun fragment rather than a verb+resource statement, though the surrounding text makes clear it fetches a contact's avatar and returns/saves the file. It implicitly distinguishes itself from the sibling chats_get_avatar by operating on contacts, but never says so explicitly. The purpose 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?

There is no when-to-use guidance, no prerequisites, and no reference to alternatives such as chats_get_avatar or storage_get. An agent must infer from the name alone whether this is the right avatar-retrieval call. Transport notes are not usage 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the transport endpoints (POST path, gRPC method, socket channel) and the word 'page', which implies paginated reads, but it says nothing about ordering, default/max page size, or auth requirements — modest added value above 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?

Very compact and front-loaded — the core purpose leads, with transport details relegated to a parenthetical. The triple endpoint notation is borderline noise for an agent, but it is contained and does not bury the main statement.

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 and three undescribed parameters, the description should carry pagination and scoping semantics; it instead stops at 'A page'. Nothing wrong is stated, but an agent lacks what it needs to page correctly or choose this over contacts_sync/search.

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 0%: page, limit, and channelId have only examples and no textual semantics. The description partially compensates by implying the channel scoping ('a channel's contacts') and pagination ('a page'), but it never explains page numbering, default or maximum limit, or how page/limit interact.

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 phrase 'A page of a channel's contacts' identifies the resource (contacts, scoped to a channel) and implies pagination, but it is a noun phrase describing output rather than a stated action, and it distinguishes nothing from siblings like contacts_get, contacts_search, or contacts_sync. An agent can guess the intent, but it must consult the name and schema to confirm this is the paginated listing operation.

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 alternatives such as contacts_search (querying by term) or contacts_sync (bulk sync). The agent is left to infer selection 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the search is scoped to a single channel, which is genuine behavioral context, but it says nothing about match semantics (partial vs exact, case sensitivity) or result limits/pagination, which matter for a search tool.

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 purpose front-loaded and transport details (REST path, gRPC method, socket name) relegated to a parenthetical. Nothing is wasted, though the transport metadata is arguably noise for an agent deciding whether to call the tool.

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 lookup with no output schema, the definition is minimally sufficient: it conveys what is searched and in what scope. It falls short on result behavior (pagination, limit semantics, empty-result handling), which an agent would need to call it well.

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 0%, so the description carries the burden. It clarifies that the query matches 'name or number' and that results are confined to one channel (implying channelId), which adds real meaning. The 'limit' parameter is left entirely unexplained in both the schema and the description.

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: 'Search a channel's contacts by name or number', which distinguishes it from contacts_list (enumerate all) and contacts_get (fetch one). It does not explicitly name those siblings, but the matching criteria make the distinction inferable.

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 'search by name or number' – an agent can infer this is for lookup rather than enumeration. However, there is no explicit statement of when to prefer this over contacts_list or contacts_get, and no prerequisites 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=false, destructiveHint=false, and openWorldHint=true, so the safety profile is partially covered. The description's parenthetical adds implementation plumbing (POST path, gRPC method, socket name) rather than behavior: it does not say whether the import merges with or replaces existing channel contacts, whether it is idempotent, or what permissions are required for a mutation operation.

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 endpoint details tucked into a parenthetical. It is tight and wastes little; the parenthetical is arguably useful to a developer agent, though borderline extraneous for tool selection.

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 mutation tool with no output schema, the description covers the core action but leaves the required channelId undocumented and omits the effect on existing contacts. It is minimally adequate rather than 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 0% for the single required parameter channelId. The phrase 'for a channel' loosely implies the parameter selects the target channel, but the description provides no format, source-of-contacts, or example details to compensate for the schema gap.

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: 'Import the platform's address book for a channel.' An agent can tell it is a bulk import of contacts into a channel context. However, it never distinguishes itself from siblings like contacts_create, contacts_list, or contacts_search, so differentiation relies on the reader's prior knowledge.

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 alternatives. The agent is not told when to sync versus create, list, or search contacts, nor what preconditions (existing channel, prior authentication) must hold.

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 openWorldHint=true, so the safety profile is covered structurally. The description adds a confirmation-before-acting requirement, which is genuinely useful behavioral context, but its 'reaches other people, deletes, or redirects data' phrasing is boilerplate that does not describe what unblocking actually changes.

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 purpose is correctly front-loaded in the first line, but the middle boilerplate sentence is vague and partly irrelevant to unblocking, and the endpoint/gRPC/socket line adds routing metadata of limited value to an agent choosing a tool.

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?

Annotations cover the mutation safety profile and there is no output schema to explain, so the description need not cover return values. However, it omits what an unblock restores (message delivery? prior status?) and leaves both identifiers undocumented, which is a real gap for a two-param mutation.

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 0% and the description says nothing about channelId or contactId, so neither parameter's meaning is clarified anywhere beyond its type and example. With two required params and zero documentation, the description fails to compensate.

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 first line states a specific verb+resource ('Unblock a contact on the platform'), which is clear and unambiguous. It does not explicitly point at the inverse sibling contacts_block or explain scope, but the action is unmistakable.

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 guidance is a generic instruction to confirm with the user first; there is no indication of when to unblock versus using contacts_block, contacts_update_status, or contacts_delete, nor any prerequisites. An agent must infer usage entirely.

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, openWorldHint=true and destructiveHint=false, so the mutation/safety profile is covered. The description adds the useful distinction that only the provider's copy is changed, but says nothing about reversibility, whether the old name is retained, or failure behavior for a non-existent contact.

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 core purpose is front-loaded in one sentence; the transport parenthetical (POST path, gRPC method, socket name) is extra but compact and potentially useful for debugging. No filler or redundancy.

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-required-parameter mutation with 33% schema coverage and no output schema, the description should clarify the identifiers and the effect of the rename. Instead it leaves channelId/contactId undefined and gives no expectations about the response or error cases.

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 only 33%: channelId and contactId carry bare examples with no documented meaning, and the description does not compensate for that gap. The 'provider's own records' phrasing loosely echoes the publicName note ('the platform is NOT told') but adds no semantics for the two undocumented identifiers.

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 ('Rename a contact') and adds a scope qualifier ('in the provider's own records'), which is enough to distinguish it from contacts_create/contacts_delete. It does not explicitly contrast with the closest sibling contacts_update_status, leaving differentiation partly to the reader.

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 indication of when to use this over contacts_update_status or contacts_sync, no prerequisites (e.g., the contact must already exist), and no note on which records are affected. The reader must infer everything from the 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=false, destructiveHint=false and openWorldHint=true, so the write/safety profile is partly covered. The description adds only transport metadata (POST/gRPC/socket) and says nothing about whether an existing status is overwritten, permission requirements, or error 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 front-loaded sentence with the operation first and the transport details parenthetically appended; nothing is redundant. Minor noise from the endpoint/gRPC/socket identifiers, but the structure is tight.

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-required-parameter mutation tool with no output schema and 0% schema coverage, the description should explain parameter intent and mutation semantics. It instead provides transport details, leaving the agent without enough to invoke 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 0% and all three parameters are undocumented. The description only hints at the 'status' field via 'status / about text'; channelId and contactId receive no explanation, so it fails to compensate for the coverage gap.

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 verb+resource ('Store a contact's status / about text') is specific and readable, and the endpoint/gRPC/socket identifiers pin it to a concrete operation. However it never distinguishes itself from the sibling contacts_update, leaving the agent to infer the difference 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?

There is no when-to-use guidance and no mention of alternatives such as contacts_update, which is the obvious ambiguous sibling. The agent gets no condition that selects this tool over the other contacts mutation tools.

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 readOnlyHint, openWorldHint and destructiveHint, so the safety profile is known. The description adds real value beyond them by disclosing that no authentication is required and pinning the HTTP method and path, which is exactly the kind of invocation 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?

Two short clauses, purpose front-loaded before the endpoint detail, zero filler. Every element 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 should ideally clarify what the probe returns or how failure is signalled, and it does not. For a simple no-arg liveness check with annotations covering safety this is a minor gap, but the return semantics are 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a parameterless tool is 4, and no parameter information is omitted or misrepresented.

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-equivalent ('Liveness probe') and the exact endpoint (GET /api/kalagh/health), so the purpose is unambiguous. However, it does not differentiate itself from the nearby siblings 'info' and 'status', 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?

'Liveness probe — no authentication required' implies the usage context (checking service availability, callable before credentials exist), which is genuinely useful. But it never states when to prefer it over 'info' or 'status', so guidance is only implied 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=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the HTTP route and that the payload identifies the served platform, but says nothing about auth requirements, caching, or response shape. With annotations carrying the main burden, this is an adequate 3.

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 clauses with the substance (what the endpoint returns) front-loaded ahead of the parenthetical route. Nothing is wasted, though the parenthetical HTTP path is arguably redundant for an MCP agent.

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 must convey the return value, and it does so at a high level ('which platform'). But for a metadata/introspection endpoint adjacent to 'health' and 'status', it leaves the agent without a clear reason to prefer it or any notion of the response structure.

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 zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-parameter tool is 4. The description cannot meaningfully add more here.

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 resource and outcome: it reports which platform (e.g. WhatsApp) this provider instance serves. That is far more informative than the bare name 'info'. It does not, however, distinguish itself from similar introspection siblings like 'health' and 'status'.

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 'health', 'status', or 'channels_get'. The description gives no context, exclusions, or alternatives, leaving the agent to guess why this metadata endpoint exists.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds one genuinely useful behavioral fact beyond that: results are paginated ('a page of'), which matters for retrieval loops. It says nothing about auth requirements, ordering, 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 line with no wasted words; the transport endpoints in parentheses are compact and skimmable. It is terse to the point of under-specification, but that is a completeness issue rather than a verbosity one.

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 5 parameters at 0% schema coverage and no output schema, the description carries the full burden for both inputs and returns, and it discharges almost none of it. It does not explain what a log entry contains or what the numeric 'level' and 'action' filters do, which are the core things an agent needs to call this 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 0% across 5 parameters, and the description names none of them. Filters like 'level' and 'action' and the paging controls 'page'/'pageSize' have no explanation anywhere, so an agent cannot know their semantics, allowed values, or defaults from this definition.

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 identifies the resource and scope ('a channel's activity log') and implies pagination ('a page of'), but it is phrased as a noun fragment describing the return value rather than stating the operation. The verb is only inferable from the tool name 'logs_list', and no sibling (e.g. logs_webhooks) is differentiated.

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 alternatives such as logs_webhooks. The agent must infer from the name alone that this is the tool for reading channel activity.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that results are channel-scoped log pages, but it does not mention pagination behavior, rate limits, auth requirements, or return format.

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 short and front-loaded, with no wasted prose. The parenthetical endpoint details are useful but could be considered extra given the lack of parameter or usage 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 read-only paginated log tool with five parameters and no output schema, the definition is materially incomplete. It relies on annotations for safety but leaves parameter semantics and usage context unexplained.

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 0% for five parameters, so the description must explain them. It implies channelId via "a channel's webhook delivery log" but offers no meaning for page, pageSize, action, or status.

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 identifies the resource precisely as a page of a channel's webhook delivery log, distinguishing it from the generic logs_list sibling. The inclusion of the HTTP/gRPC/socket identifiers further pins down the operation, though it stops short of an explicit retrieval verb.

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 guidance is given about when to use this tool versus alternatives such as logs_list. There are no prerequisites, exclusions, or contextual triggers to help an agent choose correctly.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only 'cursor page' for pagination behavior and transport trivia (POST/gRPC/socket) that doesn't help the agent; it omits roll-up details like ordering or default page 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?

Very short and front-loaded, which is good, but the parenthetical of HTTP/gRPC/socket endpoints is low-value for an agent deciding how to call the tool, and the brevity leaves required semantics unspecified.

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?

Six parameters at 17% coverage with an unexplained enum and no output schema means the definition asks the agent to guess at filtering and pagination. The description does not fill that gap, so it is incomplete for the tool's actual 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 description coverage is 17%, leaving limit, cursor, chatId, channelId and includeDeleted undocumented in both places. The description says nothing about how the types enum codes map or how cursor pagination is consumed, so it fails to compensate for the coverage gap.

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 resource – 'a chat's file-bearing messages' – which distinguishes it from generic siblings like messages_list and messages_history by scoping to attachments only. It lacks an explicit verb, but the noun phrase plus 'cursor page' makes the retrieval intent clear.

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 is given, and no alternative is named. An agent cannot tell from the description whether to pick this over messages_get_media or messages_search when hunting for files in a chat.

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 destructiveHint=true, readOnlyHint=false, and openWorldHint=true. The description adds meaningful context beyond that: the deletion is 'for everyone,' reaches other people, may redirect data, and requires user confirmation first. These are important behavioral details not captured by 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?

The description is front-loaded with the action and impact, followed by confirmation guidance and API reference details. Most sentences earn their place, though the middle sentence is slightly awkwardly worded.

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 three opaque required IDs and no output schema, the description covers the safety impact but says nothing about the parameters needed to invoke it correctly. An agent still lacks essential guidance on chatId, channelId, and messageId semantics.

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 0%, and all three required parameters (chatId, channelId, messageId) lack descriptions. The description does not mention or clarify any of them, so it fails to compensate for the schema gap and leaves the agent unable to distinguish their roles.

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 opening sentence states a specific verb and resource: 'Delete a message for everyone.' The scope 'for everyone' distinguishes it from related tools such as messages_update or messages_remove_reaction, and an agent can identify the action 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 description says to confirm with the user before invoking, which is useful operational guidance for a destructive action. However, it does not explicitly say when to use this tool versus siblings like messages_update or messages_remove_reaction, nor does it state when-not to use 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 destructiveHint=true and openWorldHint=true, and the description largely echoes that ('reaches other people... deletes, or redirects data'). The added requirement to confirm with the user before executing is genuinely useful behavioral context, but the 'deletes' wording is boilerplate drift for a forwarding operation and adds no real disclosure about side 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?

The purpose is front-loaded and the endpoint trailer is compact, but the middle sentence is generic safety boilerplate that partially duplicates the annotations and blurs the actual behavior of the tool.

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 four required parameters at 0% schema coverage, no output schema, and no annotations explaining inputs, the description needs to carry the burden of explaining the source chat/channel/message and destination semantics. It does not, leaving an agent to guess how to construct a valid forward call.

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 0% and the description explains none of the four required parameters. 'One or more chats' weakly implies toChatIds is a list, but chatId vs channelId vs messageId relationships and the source/destination distinction are left entirely to inference from names.

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 opening sentence gives a specific verb+resource ('Forward a message to one or more chats') and the endpoint/gRPC/socket trailer confirms scope. It is clear enough to separate from generic send/reply tools, though it does not name a specific sibling to contrast 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?

It advises getting user confirmation before acting, which is directional but not a when-to-use rule. No guidance on how this differs from messages_send, messages_reply, or messages_send_media, which all move content between chats.

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 destructiveHint=false, so the safety profile is covered. The description adds the dual-lookup semantics (row id vs platform id) and transport endpoints, which is useful context, but it does not disclose error behavior when neither/both identifiers are supplied or what the response contains.

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 purpose is front-loaded in a single clause, with the transport variants tucked into a parenthetical. Lean and well-ordered, with only the endpoint metadata being arguably expendable.

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 with no output schema, the description conveys how to identify a message but omits what happens on missing/ambiguous identifiers and gives no hint about the returned payload. Adequate but with clear 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 the baseline is 3. The description's 'by platform id within a channel' mirrors the schema's 'Required with platformId' note on channelId rather than adding new syntax or format details.

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 ('One message by row id, or by platform id within a channel'), and 'One message' implicitly contrasts with the sibling list/search tools. It is clear what it retrieves, though it never names a sibling to sharpen 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?

Usage is only implied by the lookup key: row id, or platform id scoped to a channel. There is no explicit when-to-use or when-not-to-use statement versus messages_list, messages_search, or messages_history, so the agent must infer 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety bar is low, yet the description still adds real behavior: the file is saved locally with its path returned, images are shown, and transport (gRPC in-band vs REST/socket provider storage) changes retrieval. It does not cover permissions or failure modes, so a 4 rather than 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?

Front-loaded with the core action and return behavior in the first two sentences; the transport detail and endpoint/gRPC suffix are compact. Minor technical framing but no wasted 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?

No output schema exists, and the description does cover the return (path returned, images shown), which is good. However it leaves the three required identifiers entirely unexplained, which is a gap for a 3-param read tool.

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 0% and all three parameters (channelId, chatId, messageId) are undocumented in both schema and description. With low coverage the description should compensate, but it says nothing about what these identifiers mean or how they relate.

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: fetching a message's media and describing it. This distinguishes it from send/create siblings like messages_send_media, though it does not explicitly name the closest alternatives such as messages_attachments or messages_get.

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 by the purpose; there is no explicit when-to-use or when-not-to-use guidance, and no routing to siblings like messages_attachments or messages_get. An agent can infer the context but must guess relative to 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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds two useful behavioral facts beyond the annotations: results are paginated ('a page') and directionally bounded ('before a given one'), plus the 'never starts a fetch' constraint on how it is invoked. It does not disclose ordering, page size, or termination behavior, so this is modest added value rather than rich context.

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 states the purpose before the transport parenthetical, and there is no filler. The POST/gRPC/socket details are somewhat noisy for an agent choosing a tool, but they are compact and clearly bracketed.

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 should carry more of the return-shape burden; it only says 'a page of stored messages.' Safety is covered by annotations and the pagination direction is conveyed, but the 0%-documented parameters and unspecified page semantics leave real gaps for a 3-parameter retrieval tool.

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 0% — the three properties carry only examples, no prose. The phrase 'before a given one' hints that messageId is the reference cursor, which partially documents one of three parameters, but chatId and channelId are left entirely unexplained in both schema and description.

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 resource and scope — a page of stored messages positioned relative to a given message, i.e. backward pagination. This is more specific than a bare noun and lets an agent infer it is a history/cursor read, but it never names or distinguishes itself from siblings like messages_list, messages_get, or messages_search.

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 hint is the parenthetical 'never starts a fetch,' which weakly implies this is for continuing backward through history rather than beginning one. There is no explicit when-to-use, when-not-to-use, or named alternative among the many message siblings, so an agent must guess when to prefer this over messages_list or messages_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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the mild hint of cursor pagination and otherwise discloses no ordering, page-size behavior, or rate/auth constraints beyond the endpoint paths.

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 compact line that front-loads what the tool returns and tucks the transport details into parentheses. No filler, though the triple endpoint notation (POST/gRPC/socket) adds little for an agent choosing a tool.

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 4 parameters at 0% schema description coverage and no output schema, the definition leaves the agent guessing about paging mechanics and channel/chat scoping. It is adequate only as a pointer to the underlying API, not as an invocation guide.

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 0%, so the description must carry the burden, yet it explains only that a cursor exists and that results belong to a chat. The limit, channelId, and cursor semantics (ordering key, direction, max page size) are undocumented anywhere.

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 resource and scope: a cursor-paginated page of a chat's messages, and names the underlying list endpoint. It doesn't differentiate from siblings like messages_history, messages_search, or messages_get, but the verb+resource pair 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?

No guidance on when to use this versus messages_history, messages_search, or messages_get, and no mention of prerequisites or paging workflow. The agent must infer selection criteria from the 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 destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds the genuinely useful behavioral detail that the mutation also marks the entire chat up to the target message as read, but the second line ('Reaches other people..., deletes, or redirects data') is generic template text that only loosely restates the destructive/open-world hints.

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 core purpose is front-loaded in the first line, which is good. The middle sentence is reusable template boilerplate rather than tool-specific content, and the trailing endpoint/gRPC/socket parenthetical is useful routing context but only marginally relevant to invocation.

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, open-world mutation with no output schema and three undocumented required identifiers, the description leaves significant gaps: no confirmation of reversibility, no indication of what the response contains, and no resolution of the chats_mark_as_read sibling overlap. It is under-specified for the operation's 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?

All three required parameters (chatId, channelId, messageId) have 0% schema description coverage and the description supplies no format, valid values, or relationship between them. It implies messageId and chatId from 'one message — and the chat up to it' but never explains channelId or how the three IDs interrelate, leaving the agent to guess.

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 ('Mark one message ... as read') and clarifies the scope: the message plus the chat up to it. This is more precise than the name alone. However, it never distinguishes itself from the sibling chats_mark_as_read, which an agent could easily confuse with this tool.

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 instruction is generic safety boilerplate ('say exactly what will happen and get the user's confirmation first'), which is not tool-specific routing guidance. There is no statement of when to prefer this over chats_mark_as_read or when the operation is inappropriate, so the agent must infer the trigger conditions.

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=true, and openWorldHint=true, so the safety profile is covered. The description adds that the reaction 'reaches other people on the platform' and advises confirming with the user, which is useful, but the 'deletes, or redirects data' clause is generic boilerplate not specific to this tool.

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 purpose is front-loaded in the first line, which is good. However, the boilerplate caution and the endpoint/gRPC/socket metadata line do not earn their place for an agent choosing a tool.

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 mutation tool with no output schema, the description leaves parameter meaning entirely undocumented and substitutes a generic warning in place of concrete behavior. Annotations cover safety, but the callable details an agent needs 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?

All four required parameters (channelId, chatId, messageId, emoji) have 0% schema description coverage, and the description adds no semantics about them — not even the accepted emoji format or ID relationships. It does not compensate for the coverage gap.

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 ('React to a message with an emoji') and clearly reads as distinct from siblings like messages_remove_reaction or messages_send. An agent can identify the operation 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?

No guidance on when to react vs. alternatives such as messages_remove_reaction or messages_reply. The second line is a generic caution template, not usage direction, so the agent gets no routing help.

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 openWorldHint=true, so the safety profile is covered structurally. The description adds a confirmation requirement ('get the user's confirmation first') and spells out the consequence that the change 'reaches other people on the platform', which is actionable behavioral context beyond the hints. It stops short of saying what happens if the reaction does not exist or whether the removal 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?

Purpose is front-loaded, followed by the safety caveat and then endpoint metadata. The parenthetical transport details (POST path, gRPC method, socket event) are useful for debugging and do not bury the core instruction, though the middle sentence is generic template text rather than tool-specific.

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 four-parameter destructive mutation with no output schema, the description omits key details: the relationship between channelId/chatId/messageId, what the response contains on success, and behavior when the reaction is absent. Annotations cover the safety profile, so the gap is not fatal, but the definition is only minimally 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 0% and the description mentions none of the four required parameters (channelId, chatId, messageId, emoji). The schema only supplies example values, so the agent gets no explanation of the ID hierarchy or the emoji format from either source; the description fails to compensate for the coverage gap.

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 first line gives a precise verb+resource ('Remove a reaction from a message'), which is immediately distinguishable from the sibling messages_react and from messages_delete. No ambiguity about what operation is performed.

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 instructs the agent to state exactly what will happen and obtain user confirmation first, which is real operational guidance for a mutation. However, it never contrasts this tool with messages_react (the inverse operation) or explains when removal is appropriate versus editing/deleting the message, 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 destructiveHint=true and openWorldHint=true, so the bar is lower. The description still adds real context: the message reaches other people externally and the agent should state the effect and obtain user confirmation first. That is genuine behavioral guidance beyond the structured hints, though the 'deletes, or redirects data' clause is boilerplate.

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?

Front-loaded with the purpose, followed by the safety warning and technical endpoint references. No wasted sentences, though the transport metadata parenthetical (POST/gRPC/socket) is of marginal use to an agent selecting the tool.

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?

This is a complex mutation with a large nested payload, no output schema, and no parameter documentation. The description does not help an agent construct the content object or understand the enum values, so it is materially incomplete for a tool of 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 description coverage is 0% for four required parameters, including a deeply nested content object with a 20-value type enum, attachments, interactive blocks, and presentation options. The only nod to parameters is 'quoting it', which loosely maps to messageId, but nothing explains chatId, channelId, or the content type codes.

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 ('Reply to a message, quoting it'), which is enough to tell it apart from messages_send at a glance. It does not explicitly name any 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 choose reply over messages_send, messages_forward, or messages_react, nor any prerequisites. The confirmation instruction is a safety step, not usage routing.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds transport plumbing (REST path, gRPC method, socket event), which is real added context, but says nothing about result volume, pagination, or how 'limit' behaves against the default.

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 core action front-loaded and transport details relegated to a parenthetical. No filler or repetition, though the transport parenthetical is only marginally useful for selection.

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 should explain what a search returns and how results are bounded, and it does not. With 0% schema coverage and no output schema, the definition is workable for a read-only search but leaves pagination and result-shape questions open.

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 0% for four parameters, so the description must carry the semantic load and largely does not. It clarifies that chatId is optional ('optionally within one chat'), but 'query' matching semantics and the meaning/default of 'limit' are left entirely undocumented.

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 ('Search a channel's messages') plus a scope qualifier ('optionally within one chat'), which is more informative than the bare name. It does not distinguish itself from near-siblings such as messages_list, messages_history, or chats_search, so an agent cannot tell which search path applies without inspecting schemas.

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 verb 'search' implies a query-driven retrieval use case versus the listing tools, and the 'optionally within one chat' clause hints at scoping. However, there is no explicit when-to-use, when-not-to-use, or named alternative among the many messages_*/chats_* 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=false, destructiveHint=true, and openWorldHint=true, so the safety profile is largely covered. The description usefully adds that the message reaches other people and that user confirmation should be obtained, but the phrase 'deletes, or redirects data' reads like generic boilerplate and is confusing for a send operation.

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 purpose is front-loaded, which is good, but the middle sentence is generic safety boilerplate that could apply to almost any tool, and the trailing transport-detail line (POST/gRPC/socket) adds little to selection. Trimmed to the first line plus addressing guidance it would be stronger.

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 a large nested payload schema, zero schema-description coverage, and no output schema, the description should explain at minimum how to target a recipient and what the content type enum encodes. Neither is addressed, and the distinction from specialized send siblings is absent, so it is not complete enough to call reliably.

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 0% across 6 parameters, including a deeply nested 'content' object. The description never explains addressing semantics — how channelId, chatId, contactId, username, and phoneNumber relate or when each is required — leaving the agent with no guidance beyond raw field names.

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 first line gives a clear verb+resource (send a message) and even indicates the payload shape (a whole MessageContent). However, with siblings like messages_send_media, messages_send_poll, messages_send_location, and messages_send_interactive, it never states that this is the generic/full-payload sender versus the specialized ones, so the agent cannot confidently route between 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 and no mention of alternatives despite an unusually dense cluster of messages_send_* siblings. The only usage-adjacent text ('get the user's confirmation first') is a safety caution, not a selection rule for choosing this tool over messages_reply or the specialized send tools.

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, openWorldHint=true and destructiveHint=true, so the safety profile is covered structurally. The description adds that the action 'reaches other people on the platform' and requires user confirmation, which is useful context beyond the annotations, but the 'deletes, or redirects data' clause is confusing and does not map to sending a vCard.

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 verb+resource is correctly front-loaded, and the endpoint/transport parenthetical is compact. However, the middle sentence is a muddled template fragment that mixes unrelated concerns (reaching others, deleting, redirecting), hurting clarity.

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 open-world, destructive mutation tool with no output schema and 0% parameter documentation, the description is too thin. It should explain the addressing model and the required contact object, and clarify what confirmation is needed, none of which it does.

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 0% across 8 parameters, and the description explains none of them. Details such as the required nested contact object (displayName + vcard), the addressing options (chatId/username/phoneNumber), or replyToMessageId are left entirely to inference from examples, so the description fails to compensate for the coverage gap.

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 contact card (vCard)'. This clearly distinguishes it from sibling send tools like messages_send_media or messages_send_location by the payload type. It does not explicitly name an alternative, but an agent can tell what it does at a glance.

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 clear when-to-use guidance, no alternatives named among the many messages_send_* siblings, and no prerequisites. The second sentence ('get the user's confirmation first') is a generic caution rather than routing guidance, and it is tangled with an unrelated clause about deleting/redirecting data.

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 openWorldHint=true, and the description stays consistent with them while adding the useful instruction to state effects and obtain confirmation first. It still leaves the important specifics undisclosed: exactly what is created or overwritten, which recipient identifiers are required, and whether the call is idempotent.

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