WhatsMCP: MCP for WhatsApp

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

Annotations already declare readOnlyHint=true, but the description adds real behavioral detail beyond them: the full status vocabulary, the fact that summary/success/collected-data/transcript only exist once the call has ended, and a one-hour expiry on recording_url. Those are exactly the operational details an agent cannot get from the structured fields.

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

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

One front-loaded sentence: verb and resource first, then the status list, then the post-completion fields. The tail is cumulative and dense, but every clause (status set, post-end availability, URL expiry) carries information an agent needs.

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

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

Return shape is backed by an output schema, yet the description still tells the agent which fields are conditional and when the recording link expires. Nothing needed to invoke this correctly is missing.

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

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

The single call_ref parameter is 100% documented in the schema, and the description only restates its origin ('started with wa_ai_call_start'). With coverage this high the schema is doing the work, so baseline 3 applies.

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

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

The description opens with a specific verb+resource ('Read an AI call') and immediately scopes it to calls created by wa_ai_call_start, which cleanly separates it from wa_ai_list_calls and wa_ai_call_hangup. The enumerated status values confirm exactly what kind of object is returned.

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?

'Read an AI call started with wa_ai_call_start' establishes the prerequisite and implies polling, since statuses like dialing/in_progress indicate it is meant to be called before the call ends. It never names a sibling alternative or states an explicit when-not condition, so it falls short of a 5.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds real substance: the hangup is immediate and affects both parties, and calls that have already ended are left untouched with hung_up false. That tells the agent what actually happens on a repeat call, beyond the bare idempotency hint.

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

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

Three short sentences, front-loaded with the action, then effect, then downstream result and the idempotent edge case. No filler or restatement of the title.

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

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

For a single-parameter mutation with annotations and an output schema present, the description covers everything an agent needs: what it does, who it affects, what happens on repeat invocation, and where the artifacts surface afterwards.

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 (call_ref) at 100% schema coverage, so the schema already explains it fully. The description adds a little framing by implying the ref must reference a live call, but no format or sourcing detail beyond what the schema states.

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 precise verb+resource: 'End a live AI voice-agent call', and scopes it to calls started via wa_ai_call_start or answered incoming calls. That distinguishes it cleanly from wa_ai_call_start (initiate) and wa_ai_call_get (retrieve results) without needing the 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?

Explicitly says which calls it applies to (ones started with wa_ai_call_start or answered by an agent) and routes the agent to wa_ai_call_get for the resulting summary/transcript/recording. It also carves out the no-op case (already-ended calls). It does not name wa_ai_list_calls as the way to obtain a call_ref, which the schema does instead.

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

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

Goes well beyond the annotations: it discloses that the tool is asynchronous ('returns immediately with a call_ref; the call then rings and runs on its own'), names the terminal statuses, and states the concurrency/cooldown limits that explain the non-idempotent, non-read-only annotation profile. This is the kind of context the structured fields cannot carry.

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

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

Four sentences, front-loaded with the action, then the return shape, then the polling loop, then the constraints. No filler and nothing important is buried.

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

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

For an async mutation tool with an output schema and full schema coverage, the description supplies everything an agent needs: how the call is started, that it returns a call_ref, how to observe completion, and the concurrency limits that cause failures.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including variables merge semantics and format examples. The description only restates that per-call context goes in variables and the preset comes from wa_ai_list_presets, adding little beyond the schema baseline.

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 ('Have an AI voice agent call a WhatsApp number from one of your numbers') plus the required configuration source (a preset). It is unambiguously distinct from wa_ai_call_get, wa_ai_call_hangup and wa_list_calls, which it does not rely on the name alone to separate.

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

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

Explicit about the prerequisite (preset from wa_ai_list_presets), the follow-up workflow (poll wa_ai_call_get about every 30 seconds until status is done/failed/no_answer/busy), and the constraints (one call at a time per number, cooldown after a call finishes). An agent knows exactly when to use this and what to do next.

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

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

Annotations already declare readOnlyHint and idempotentHint=false, so safety is covered; the description adds real context beyond that: newest-first ordering, pagination via a call_ref from the previous page, and how to interpret the direction and from fields on inbound calls. It does not discuss whether the full history or only a recent window is available, which is the one remaining behavioral unknown.

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

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

Two sentences, zero waste, and the decisive information (what is listed, ordering) is front-loaded before the follow-up routing hint. Dense but every clause carries meaning.

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 lister with an output schema, 100% parameter coverage, and annotations covering safety; the description supplies scope, ordering, pagination pattern, and the next-step tool. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and both parameters are documented in the schema (limit 1-100 default 25; before as a call_ref from the previous page). The description's mention of 'newest first' and the cursor-style paging corroborates but does not extend the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List this workspace's AI voice-agent calls, newest first') and then defines exactly which calls qualify: outbound calls started with wa_ai_call_start and inbound WhatsApp calls answered by a preset with answers_inbound true. This scope definition is what separates it from the generic wa_list_calls, so an agent can distinguish it without opening either schema.

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

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

Explicitly routes the agent forward: 'Use a call_ref with wa_ai_call_get for the transcript and recording link.' That is clear context for the natural follow-up. It does not, however, state when to prefer the sibling wa_list_calls (non-AI calls) or anything about what is excluded, leaving one plausible routing question unanswered.

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?

While annotations cover the safety profile, the description provides vital operational context: a preset pairs multiple entities (agent/number/vars) and dictates the caller's logic regarding the 'ready' status and 'not_ready_reason'. This adds significant value 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?

The definition is densely packed but highly efficient. Every sentence delivers a specific piece of actionable information, progressing from definition to usage and finally to dependency requirements.

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?

Given that it is a 0-parameter read-only list operation, the description is perfectly complete. It addresses the 'how' (call start) and the 'status' (ready=true) needed for successful integration.

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

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

With zero parameters and 100% schema coverage, the baseline is strong. The description compensates slightly by defining the structure of the resource itself (what the preset object contains), ensuring the agent understands the context of the returned data.

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?

It clearly states the action ('List') and the specific resource ('AI voice-agent presets'). Furthermore, it defines what a preset encompasses (agent, WhatsApp number, variables), providing immediate conceptual clarity.

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 provides explicit instructions on how to consume the output by naming the required sibling tool (wa_ai_call_start). It also provides necessary run-time usage logic, stating that only presets with 'ready=true' can be used.

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?

Adds genuine behavioral context beyond the annotations: the real-world consequence (contact can no longer call or message) and the shape of the result (number, address-book name, country). Annotations declare readOnlyHint=false and destructiveHint=false but say nothing about effect; the description fills that gap. It stops short of noting auth requirements or behavior on already-blocked/unknown contacts.

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

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

Two sentences, front-loaded with the primary operation and the consequence, followed by the alternate mode and result shape. No filler; every clause carries information.

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

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

With a complete input schema, an output schema, and presence annotations, the description covers the remaining burden (effect of blocking, unblock mode) well. Minor gaps: no guidance on idempotency/already-blocked contacts and no cross-reference to wa_list_blocked, which sits right next to this 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 100%, so jid, account_id, and unblock are already fully documented (including the 'as returned by wa_list_accounts' hint). The description restates the unblock toggle and adds no new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (block/unblock) on a specific resource (a contact on a WhatsApp account), plus the concrete effect ('can no longer call or message it'). Cleary distinguishes the two modes via the unblock flag, so an agent knows exactly what it does without opening the schema.

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

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

Gives clear context for use ('on one of your WhatsApp accounts') and explains the toggle case — set unblock=true to unblock rather than calling a different tool. It does not, however, reference siblings such as wa_list_blocked for checking current block state, nor does it state exclusions (e.g., what happens if the contact is already blocked).

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

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

Annotations already declare non-read-only and non-idempotent, and the description adds the useful downstream behavior: the returned JID should be passed to wa_send_message's 'to'. It does not warn that retries create duplicate groups (relevant given idempotentHint=false), which is a missed opportunity for a mutating 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?

Two sentences, front-loaded with the action and immediately followed by the return value and the cross-tool handoff. No filler or redundant restatement of structured fields.

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?

Given an output schema exists, the description needn't explain returns, yet it usefully names the JID and invite link and links the JID to a sibling call. The only gap is the absence of any warning about non-idempotent behavior or account validity prerequisites for a mutation 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 100%, so the schema already carries the detailed semantics (25-char name limit, E.164/JID member formatting, excluding your own number). The description only restates 'name and initial members' at a high level, adding no meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Create a WhatsApp group') plus the required inputs, so the action is unambiguous. It does not explicitly distinguish itself from nearby siblings such as wa_join_group or wa_update_group, leaving that inference to the 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?

Usage is only implied by the verb 'Create' and the phrase 'from one of your accounts', which hints at an account prerequisite. There is no explicit when-to-use versus wa_join_group/wa_update_group guidance and no mention of failure or prerequisite 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?

Beyond annotations, the description discloses the asynchronous Meta review process, typical review duration, and the APPROVED-gating requirement before the template can be used. It also clarifies that body variables must be numbered in order with one example per variable, which is important behavioral context for submission.

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 core action and review workflow, then adds only high-value constraints about categories, variables, examples, and Business-only applicability. Every sentence carries useful information without unnecessary repetition.

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

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

Given the 11-parameter schema, full schema coverage, annotations, and an output schema, the description provides the necessary workflow context: review, approval gating, Business-number restriction, category constraints, and variable/example expectations. An agent has enough information to invoke the tool correctly without needing return-value details in the description.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters in detail. The description reinforces category, body-variable ordering, and body_examples alignment, but most parameter semantics are carried by the schema rather than the description, making 3 the appropriate baseline.

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: submit a new WhatsApp Business message template for Meta review on a Business (Cloud API) number. It also distinguishes the creation action from downstream use by naming wa_list_templates for approval status and wa_send_message for sending an approved template.

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 context is clear: this creates a template for Meta review, templates only apply to Business numbers, categories must be MARKETING or UTILITY, and sending is only possible after wa_list_templates shows APPROVED. It does not explicitly contrast with sibling operations like wa_delete_template, but the create-specific purpose is unambiguous.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds the critical non-obvious behavior that WhatsApp has no true group-delete and the group is emptied and exited instead. That is exactly the kind of consequence an agent needs before invoking a destructive operation, plus the auth prerequisite.

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

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

Three short sentences, action first, then precondition, then the caveat that explains the mechanism. No filler and nothing that could be cut without losing information.

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

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

For a two-parameter destructive mutation with full annotation coverage, a complete schema and an output schema, the description covers purpose, authorization requirement, and the surprising side effect. Nothing an agent needs in order to decide or call is missing.

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

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

Schema description coverage is 100% and both parameters (group_jid, account_id) document where their values come from, so the schema does the heavy lifting. The description only implies that group_jid identifies the target and adds no format or edge-case detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('Delete a WhatsApp group') and immediately explains the mechanism — remove every other member then leave — which is exactly what separates it from wa_leave_chat and wa_remove_participants. An agent can distinguish the three without opening any schema.

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

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

Gives a hard prerequisite ('The account must be a group admin'), which is real usage guidance for selecting and calling it correctly. It stops short of explicitly naming alternatives such as wa_leave_chat for a non-admin exit, so the when-not case is left to inference.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the safety profile is covered; the description still adds real value by explaining that this is a revoke rather than a true delete and that modern clients honour it. It stops short of stating irreversibility or any time-limit/failure conditions on revocation.

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

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

Two tight sentences, the action front-loaded and the semantic caveat immediately after. Every clause earns its place — nothing redundant with the schema or annotations.

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?

An output schema exists and all four parameters are fully documented, so the description's only remaining burden is the action's semantics — which it covers by explaining revocation. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already explains chat, sender, account_id and message_id in detail; the description adds no parameter-level guidance. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ('Delete a WhatsApp message') plus the scope 'for everyone', which separates it from wa_edit_message and the unrelated delete siblings (wa_delete_group, wa_delete_template, wa_delete_webhook). The revocation clarification further pins down what kind of delete this is.

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

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

Usage is only implied: the revocation note tells the agent this removes a message for all recipients, but it never states when to prefer this over wa_edit_message, nor any precondition (e.g. only your own messages unless admin, per the sender param). No explicit when/when-not 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 destructiveHint=true and idempotentHint=false, so the description's added value is the Meta-side consequence: a deleted template's name is blocked from reuse for a while. That is genuinely useful non-obvious behavior, though it stops short of saying what happens when the name or language doesn't exist.

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

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

A single front-loaded sentence that packs scope, the language-omission rule, and the name-reuse warning 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?

An output schema exists and annotations cover the destructive profile, so the description only needs scope and side effects, both of which it supplies. The one gap is behavior on invalid name/language or partial multi-language deletion failures, which an agent might reasonably want before invoking a destructive 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 coverage is 100% and the schema already documents all three parameters including the 'omit to delete every language' semantics. The description only restates the language-omission rule and adds no format details (e.g. case sensitivity, locale validation), so baseline 3 applies.

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

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

Specific verb (delete) plus resource (WhatsApp Business message template) and scope (one language, or all languages when omitted). It is clearly distinguishable from the sibling wa_create_template and from other wa_delete_* tools that target messages, groups, or webhooks.

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

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

The description implies when to use it by describing the two deletion modes, but it never names the alternative (e.g. wa_list_templates to find the name first, or wa_create_template to recreate) and gives no prerequisites such as permissions or confirming the template exists. Usage is inferable but not spelled 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by clarifying the blast radius — inbound messages keep arriving and stay readable via wa_list_messages, only the push stops — which tells the agent no data is lost. It stops short of saying whether the endpoint configuration is removed irreversibly or what happens on a second call.

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

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

Two short sentences with zero filler; the effect leads and the important reassurance (messages still readable) follows immediately. Every clause earns its place.

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

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

An output schema and annotations carry the return and safety details, so the description only needs the behavioral picture, which it largely provides. The remaining gap is whether deleting the webhook is reversible or errors when no webhook is configured — a real but minor omission for a zero-parameter 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level claims are made or needed.

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 action (stop push delivery) rather than restating the tool name, and describes the effect in user terms. However, it never distinguishes deletion from mere disabling, despite the sibling wa_enable_webhook sitting right next to it — an agent cannot tell whether this removes the endpoint configuration or just pauses 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?

The usage context is only implied: 'stop delivering inbound messages' suggests when to call it, and the note that messages remain available points an agent at wa_list_messages as the fallback. There is no explicit when-to-use/when-not, and no routing guidance versus wa_set_webhook or wa_enable_webhook.

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 but non-destructive mutation, and the description adds platform-specific behavioral context the annotations cannot: the ~20-minute edit window enforced by WhatsApp. It does not say what happens when the window has expired (error vs silent no-op), which keeps it from a 5.

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

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

Two short sentences with no filler; the core action comes first and the constraint second. Every sentence carries information the agent needs.

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

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

An output schema exists, so return values need no explanation, and the full parameter set is described in the schema. What remains is failure behavior past the 20-minute cutoff, which would help the agent decide between retrying and sending a new message.

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 chat, text, message_id and account_id are already fully documented, and description adds little per-parameter detail. The 20-minute rule implicitly constrains which message_id values are valid, but the description does not state this about the parameter directly. Baseline 3 applies.

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

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

States a specific verb and resource ('Edit a WhatsApp message you sent'), so the agent can distinguish it from wa_send_message and wa_delete_message by intent. It stops short of naming the sibling tools it supersedes in a given situation, 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 gives two concrete applicability conditions: the message must be one 'you sent' and the edit must occur within roughly 20 minutes of the original. That is real guidance an agent can act on, though it never explicitly contrasts with alternatives such as sending a new message instead.

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 signal non-destructive, idempotent mutation, but the description adds genuine operational context beyond them: credentials are preserved, delivery halts rather than data, and inbound messages continue to accumulate and remain readable. That is exactly the kind of side-effect detail annotations cannot express.

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

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

Three short sentences, front-loaded with the core action and the non-obvious constraint (secret preservation), then the usage scenario, then the follow-on reference. Nothing is repeated for 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?

An output schema exists, so return values need no explanation. With annotations covering safety and idempotency, and the description covering state effects and post-pause behavior, an agent has everything needed to invoke 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 coverage is 100% and both parameter descriptions already explain that true resumes, false pauses, and that the endpoint/secret are kept. The description's 'WITHOUT changing the endpoint or its signing secret' reinforces the enabled flag but adds no new syntax or edge-case meaning, so the baseline of 3 applies.

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

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

States the specific action (pause or resume webhook delivery) and the resource (the configured webhook) with emphasis that the endpoint and signing secret are untouched. This cleanly separates it from wa_delete_webhook and wa_set_webhook, which are the siblings an agent could otherwise 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?

Explicitly frames the when-to-use case ('stop deliveries temporarily') and the when-not case by naming the destructive alternative ('deleting and re-creating the webhook would issue a new secret'). It also points to wa_list_messages as the path for messages received during a pause, so the agent knows what to do next.

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 disclose the mutating, non-idempotent, non-destructive profile. The description adds the useful detail that the action is scoped to a specific account and driven by a channel link, but it stays silent on what happens on a repeat follow or whether the channel appears in wa_list_channels 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?

A single well-formed sentence with the action and the two required inputs front-loaded. There is 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?

An output schema exists, so return values need not be explained, and both required parameters are covered by the schema. What the description omits is the behavioral edge cases (already-following, invalid invite key, rate limits) that an agent needs before invoking a non-idempotent 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 coverage is 100%, and the schema even names wa_list_accounts for account resolution and the accepted link formats. The description's phrasing ('from one of your accounts', 'using its link') just restates both parameters, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Follow a WhatsApp Channel'), plus the qualifier 'from one of your accounts using its link'. That clearly separates it from wa_join_group and wa_list_channels, though it doesn't name those siblings explicitly.

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

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

The description never says when to choose this tool over alternatives (e.g. wa_list_channels to inspect first) or what happens if the account already follows the channel. Usage is only inferable from the name and title.

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 the description adds real behavioral detail beyond them: results are ordered oldest-first, the `chat` form includes history loaded via wa_load_history, and the time window is on send time with exclusive `until`. It does not explain the idempotentHint=false result (e.g. signed media URLs / shifting window), which is the one behavioral question left open.

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 verb and resource, and every clause carries weight (scope switch, ordering, history, sibling routing, time semantics). It is a single dense sentence, though, so the two distinct modes are slightly harder to parse than they need be.

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?

An output schema exists, so return values need not be explained, and the description still covers ordering, default account scope, and history inclusion — enough to call it correctly. Missing only minor operational context such as the default limit and what happens when `chat` is an unknown JID.

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

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

Schema description coverage is 100%, so every parameter is already documented in detail (limit range, RFC3339/date formats, media URL expiry). The description only restates the since/until and chat semantics, adding no syntax or edge-case information beyond the schema — baseline 3 applies.

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

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

States a specific verb and resource (read recent messages) plus the scope switch: account-wide by default, single conversation when `chat` is supplied. It also names the sibling used for paging (wa_list_messages), so an agent can separate it from wa_get_message and wa_list_messages without opening either schema.

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

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

Gives an explicit use case ("for context before replying") and an explicit alternative with its condition ("use wa_list_messages to page through everything new"). It also points at wa_load_history as the source of older history, so the routing decision is fully determined.

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 declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description usefully adds that reset=true revokes the existing link and that admin rights are required — the two facts an agent most needs before calling. It does not flag that revocation is irreversible for existing members or what error appears for non-admins, so it improves on annotations without fully covering them.

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

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

Two sentences, zero filler, with the primary action first and the destructive variant second. The admin prerequisite is appended where it is cheap to read.

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 a full input schema, an output schema and annotations present, the description only needs to carry prerequisites and mode behavior, which it does. Minor gaps remain on failure behavior for non-admins and whether the old link dies immediately after reset.

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

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

Schema coverage is 100%, with per-parameter descriptions already explaining reset, group_jid (…@g.us from wa_list_groups) and account_id (from wa_list_accounts). The description's mention of reset adds no semantics beyond the schema text, so the baseline 3 applies.

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

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

States a specific verb and resource (get a WhatsApp group's invite link) and explicitly covers the two modes: plain retrieval versus reset=true revocation plus reissue. No sibling tool touches invite links, so the agent can distinguish it immediately.

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?

'set reset=true to revoke it and issue a new one' gives a clear condition for the non-default mode, and 'The account must be a group admin' states a prerequisite. It stops short of naming exclusions or what to do on failure, keeping it at a strong 4 rather than a full when/when-not treatment.

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

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

The description goes far beyond standard annotations by detailing the behavioral differences in the output: small attachments return `media_base64` while large ones return a `media_url`. It also explains the meaning of the 'refused' status.

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

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

The description is dense and informative but logically structured. It front-loads the primary function and then elaborates on the operational details (output types, failure modes) and dependency.

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

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

The definition is complete for this specific use case. It covers what is fetched, how the output will look (URL vs Base64), the required input source, and the negative result, which covers all necessary concerns for an AI agent.

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?

Although schema coverage is 100%, the description provides essential semantic guidance by specifying that `message_id` must be retrieved specifically from `wa_list_messages`. This context is vital for correct orchestration.

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 tool is clearly defined to fetch media attachments (image/video/audio/etc.) from a received WhatsApp message. The naming convention and description immediately establish its purpose within the communication context.

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 provides a crucial usage dependency: the `message_id` must be sourced from the `wa_list_messages` tool, preventing agents from using arbitrary IDs. It also defines the failure state ('refused').

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 the description reinforces the non-mutating single-record read while adding that the caller avoids paging. It also points out that media bytes are normally fetched separately, though it does not state what happens when neither cursor nor message_id resolves.

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

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

One sentence for the what and keys, a second for the when, front-loaded with no filler. Every clause carries information an agent can act on.

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 a full output schema and fully described parameters, the description only needs to justify the lookup path and the intended use, both of which it covers. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents cursor vs message_id and the 1h signed media URL. The description only echoes that message_id comes from a webhook or wa_list_messages and adds no format or precedence detail beyond the parameter definitions, so baseline 3 applies.

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

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

States a specific verb and resource ('Fetch ONE stored message') and names the exact lookup keys (message_id or cursor). The capitalized 'ONE' plus 'without paging through history' separates it cleanly from wa_list_messages.

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

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

Gives concrete triggers: read the message a webhook told you about, or the one you are about to react to, edit or delete. It implies history browsing belongs to wa_list_messages rather than naming it as the alternative with an explicit exclusion, so the routing guidance is clear but not fully spelled 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?

The readOnlyHint: true annotation is consistent with a 'Show' operation, and the description adds substantial behavioral context beyond the annotation: per-number plan gating, excluded_tools semantics, the 'mixed' plan case, and why a tool may work on one number but be refused on another. This is exactly the kind of plan-enforcement information an agent needs before calling dependent tools.

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 and every major clause carries useful information, but it is a dense, long paragraph with several semicolon-separated qualifications. It remains readable for a complex diagnostic tool, though a little more structure would improve scanability.

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?

Given the output schema and read-only annotation, the description supplies the remaining context an agent needs: when to use it, how the account_id scope changes the results, and how to interpret plan-based tool refusals. Nothing essential for correct invocation appears to be missing.

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

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

Schema description coverage is 100%, so the basic meaning of account_id is already documented. The description still adds real meaning beyond the schema by explaining the different excluded_tools interpretation for one number versus the workspace and the 'mixed' plan result when omitting account_id.

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: it shows a plan, its limits, and current usage. It also clearly distinguishes the two scopes, one number with account_id versus the whole workspace without it, which lets an agent separate this from sibling listing and messaging tools.

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

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

It explicitly says when to call it: to diagnose plan_required errors, understand why wa_send_message may be refused, or check remaining headroom. It also explains the key usage decision, passing account_id for one number and omitting it for every number, so the agent does not have to infer the 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, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: results are scoped to the querying account, and an empty about/picture reflects non-sharing rather than absence of data — a real interpretation pitfall it preempts. It does not address the idempotentHint=false nuance, which is a small remaining gap.

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

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

Two sentences, front-loaded with the purpose and return fields, followed by the one caveat that actually changes interpretation. No wasted 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?

An output schema exists so return structure needn't be explained, and the description covers the account-scoping and partial-data caveats. Adequate for a 2-parameter read tool; only the non-idempotent read behavior 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%, including the international phone format example and the wa_list_accounts provenance for account_id, so the schema does the heavy lifting. The description reinforces account scoping ('from one of your accounts') but adds no format or default details beyond the schema.

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

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

States a specific verb and resource ('Look up who a phone number is on WhatsApp') and enumerates exactly what is returned: registration status, public name, about, picture, and for businesses categories/contact/hours. This is clearly a single-peer lookup, distinct from sibling list tools like wa_list_contacts or wa_get_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?

Usage is implied by the phrasing 'from one of your accounts' and the reference to picking an account, but there is no explicit when-to-use vs when-not guidance and no sibling tool is named as an alternative (e.g., wa_get_chat for known contacts).

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

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

Beyond the readOnlyHint annotation, the description discloses meaningful behavior: it never returns the signing secret, it reports whether the webhook is enabled, and it provides the reason if disabled. This tells the agent exactly what to expect and what not to expect, which is especially valuable for a read 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?

Two sentences with no waste. The primary function is front-loaded, and the privacy caveat is placed second where it can warn the agent before it relies on getting the secret. Every clause earns its place.

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

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

For a zero-parameter read tool with an output schema and readOnlyHint, the description covers the essential behavioral context: what is returned, what is deliberately omitted, and how disabled state is presented. No additional information is needed to invoke or interpret this tool correctly.

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

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

The tool has zero parameters, so the description correctly adds no parameter explanations. With 100% schema coverage and an empty input schema, there is nothing more an agent needs to know about 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?

The description uses a specific verb ('Show') and a clear resource ('currently configured inbound webhook'), then adds distinctive detail: it reports enabled state and disable reason, and explicitly notes the signing secret is excluded. This differentiates it from wa_set_webhook, wa_enable_webhook, and wa_delete_webhook without needing those names.

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 'currently configured' and the read-only framing make it clear this is for inspecting existing webhook state, not creating, enabling, or deleting. The signing-secret caveat also implies that if the agent needs the secret, it must use the creation flow instead. However, it does not explicitly name the alternative tools or state when not to use this one.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false, so the safety profile is covered; the description adds only the invite-link mechanism, which is already a parameter. It says nothing about what happens if the account is already a member, if the link is expired, or whether admin approval is required — meaningful gaps for a non-idempotent mutation.

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

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

A single well-formed sentence with the action front-loaded and zero filler. There is little structure to speak of, but nothing is wasted.

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

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

An output schema exists so return values need not be explained, and both required params are described in the schema. However, for a non-idempotent write operation with group-membership side effects, the description omits failure and idempotency behavior the agent would need to call it 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 100%, and both parameters (account_id via wa_list_accounts, invite_link accepting either a full URL or bare code) are fully documented there. The description adds no meaning beyond that, so baseline 3 applies.

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

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

States a specific verb+resource ('Join a WhatsApp group') plus scope ('from one of your accounts') and mechanism ('using its invite link'), which cleanly separates it from wa_create_group and wa_get_group_invite_link. It stops short of naming any sibling explicitly, so it lands at 4 rather than 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?

No guidance on when to use this versus wa_create_group, wa_update_group, or wa_follow_channel, and no exclusions or prerequisites. The agent must infer usage from the verb alone.

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

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

The annotations already mark the tool as destructive and non-idempotent, but the description reinforces the behavioral implication of the action itself—namely, that it changes the user's membership status in the chat/channel. This adds necessary high-level context without redundancy.

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 extremely concise, communicating the core function of the tool in a single, efficient sentence. It avoids jargon and unnecessary 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?

Given that the output schema is present and the input parameters are well-defined, the description is complete enough to enable an agent to select and invoke the tool correctly. It clearly defines the target of the action.

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?

Since the schema coverage is 100%, the description provides little additional semantic value beyond repeating the information already supplied in the schema descriptions. It mentions the resource type (group/channel) but adds no unique constraints 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?

The description precisely identifies the two types of actions: leaving a group or unfollowing a channel, and specifies the required identifier (JID) for both. This distinguishes its function clearly from other potential messaging actions.

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?

While it clearly states *how* the tool operates (by JID), it provides no guidance on when to use this tool versus siblings like `wa_join_group` or `wa_follow_channel`. The usage context 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 cover the read-only profile, and the description adds genuine domain semantics: an account is only usable while state is 'connected' (status 'live'), otherwise status and what_to_do explain the failure. That tells the agent how to interpret results and why a listing may look unusable, which is more than the annotations convey.

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

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

Three tight sentences, front-loaded with the action, then the decision rule, then the state semantics. Every clause carries information the agent needs; nothing is padded.

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

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

An output schema exists, so return fields need not be enumerated, yet the description still explains how to read the state/status/what_to_do fields. Combined with the covered safety annotations and parameterless schema, the definition is complete for correct 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline applies. No misleading parameter hints are introduced.

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

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

States a specific verb and resource ('List the WhatsApp accounts'), and implicitly distinguishes itself from message-derived data by saying a message row's account_id should normally be reused. It never names an actual sibling tool, so the differentiation is contextual rather than explicit, but an agent can still tell what this returns.

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

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

Gives explicit when-to-use triggers (before a first message to a number with no history, or diagnosing an account that is not working) and an explicit when-not-to-use rule (reuse the row's account_id when replying). This is the rare case where both the positive and negative conditions are 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 cover the read-only safety profile, and the description goes further by disclosing data limitations an agent would otherwise probe for: the name field is absent for unsaved numbers, and block timestamps are unavailable because WhatsApp doesn't report them. The one gap is that idempotentHint=false is unexplained for what reads like a stable list 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?

Three short sentences, front-loaded with the action, then the return shape, then the caveat that pre-empts a wrong assumption. No sentence is 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?

A read-only single-parameter list tool with an output schema and safety annotations needs little more; the description still covers scope, entry contents, and the missing-timestamp caveat. Nothing required to invoke it correctly is absent.

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

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

There is a single parameter with 100% schema description coverage, and the schema already explains it is the account whose blocklist is read. The description adds no further parameter semantics, so the baseline 3 applies.

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

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

States a concrete verb and resource — list the contacts a given account has blocked — which cleanly separates it from wa_list_contacts and wa_block_contact without needing the schema opened. The scope qualifier 'one of your accounts' makes the per-account nature explicit.

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

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

Usage is implied by the 'blocked' qualifier but the description never states when to reach for this instead of wa_list_contacts, nor any prerequisite such as pairing status. The tool-chaining hint ('as returned by wa_list_accounts') lives in the schema, not the description.

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 read-only safety, so the description's value is in disclosing ordering (oldest first), the termination condition for pagination, and that each call reports answered status and duration. It does not state rate limits or what happens if the cursor is stale, but the core loop behavior is well 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?

Four short sentences, scope first, pagination mechanics next, filters last. No filler and no restatement of the title.

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

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

With an output schema present and full parameter descriptions, the description only needs to cover workflow and ordering, which it does. The gap is sibling disambiguation against wa_ai_list_calls, the one thing an agent still has to guess.

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 baseline is 3; the description earns extra by explaining the cursor round-trip contract ('pass back the next_cursor you were given') and reiterating that until is exclusive, which is easy to get wrong even when documented in 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?

Opens with a specific verb and resource — 'Read call history across your WhatsApp accounts' — and states the ordering (oldest first). It does not distinguish itself from the sibling wa_ai_list_calls, so an agent cannot tell from the description alone which of the two list-call tools applies.

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

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

Gives concrete operational guidance: page with after_cursor, feed back next_cursor, continue until has_more is false, and narrow with since/until. It lacks a when-not-to-use or which-alternative clause (notably versus wa_ai_list_calls and wa_load_history).

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?

Read-only behavior is already covered by readOnlyHint=true, and the description adds the returned fields (JID, name, subscriber count). It does not disclose pagination, rate limits, or the meaning of idempotentHint=false, but the output schema reduces the need for return-format details.

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

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

A single front-loaded sentence with no wasted words. It states the operation and the useful return fields compactly.

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 one-parameter read tool with an output schema and annotations, the description is nearly complete. It could mention pagination or result limits, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, and the single account_id parameter is documented in the schema as coming from wa_list_accounts. The description's phrase 'one of your accounts' reinforces scope but adds no syntax or selection details beyond the schema.

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

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

States a specific verb and resource: list channels followed by one of the user's accounts, and names the returned fields. This clearly distinguishes it from the sibling write tool wa_follow_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?

The description gives clear context: use it to list channels followed by a specific account. It does not explicitly state exclusions or alternatives, but the sibling set contains no competing list-channels 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 only cover the read-only safety profile, and the description adds genuinely non-obvious behavior: include_pictures triggers live WhatsApp lookups per contact, caps the page at 10, and 'can take half a minute.' That latency/cap tradeoff is exactly the kind of operational trait an agent cannot infer from readOnlyHint.

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

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

Four sentences, front-loaded with the core action, then query semantics, then the forward reference, then the costly optional flag. Every sentence carries information, though the include_pictures explanation overlaps heavily with the schema's own description of that parameter.

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 list tool with an output schema, 100% parameter coverage, and 5 params, the description covers purpose, matching semantics, the performance trap, and the downstream use of results. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by disclosing match fields the schema omits — 'saved names, the name the contact publishes, business names and the number.' It restates include_pictures and cursor behavior already well documented in the schema, so it doesn't reach 5.

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 with scope: 'List or search the address book of one of your WhatsApp accounts — the contacts saved on the phone this account is linked to.' That scoping sentence alone separates it from wa_list_blocked, wa_list_group_members, and wa_get_profile, so an agent can pick the right tool without opening 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?

Explicitly tells the agent when to pass query ('to find someone by name or number; omit to list everything') and when to set include_pictures (only when picture URLs are needed, at a page/latency cost). It also routes forward with wa_send_message. It stops short of naming competing tools (wa_list_blocked, wa_get_chat) or stating when this tool is the wrong choice.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds value by clarifying the output item shape: each item has a JID, a phone number stored in 'name', and an 'admin' flag. It does not mention pagination or error behavior, but the output schema covers return values.

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

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

Two tightly written sentences, front-loaded with the purpose and followed by essential output field semantics. No wasted words.

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

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

Complete for a simple list tool: purpose, output fields, and annotations are sufficient. Missing only minor behavioral details like pagination or group-existence preconditions, but the output schema and annotations cover the bulk of what an agent needs.

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

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

Schema description coverage is 100% and both parameters have descriptive text pointing to wa_list_groups and wa_list_accounts. The description adds no parameter meaning beyond the schema, so 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: 'List a group's members.' Clearly distinct from wa_list_groups and wa_list_contacts, but doesn't explicitly name those siblings or contrast 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?

Usage is implied by the name and resource, but the description gives no explicit when-to-use, when-not-to-use, or alternative tool (e.g., wa_list_contacts for non-group members).

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 idempotentHint=false. The description usefully adds that only joined groups are returned (not discoverable/created ones) and what fields come back, but it does not explain why the call is non-idempotent, whether results are ordered, or how they behave for large group lists. With annotations covering the safety profile, this is adequate but thin.

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

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

A single well-formed sentence that front-loads the action and scope and closes with the returned fields. No filler, nothing to trim.

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?

An output schema exists, so return values need only be summarized and they are. For a one-parameter read tool with full schema coverage and clear annotations, the description is sufficient, missing only ordering/pagination expectations that could matter for accounts in many groups.

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

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

Schema coverage is 100% and the single account_id parameter is already documented in the schema with a cross-reference to wa_list_accounts. The description adds no format or sourcing detail beyond that, so the schema carries the load — baseline 3.

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

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

States a specific verb and resource (list groups) with an explicit scope qualifier (groups 'one of your accounts has joined') and previews the returned fields (JID, name, member count). This separates it from wa_create_group and wa_list_group_members, though it never names those siblings directly.

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 'one of your accounts has joined' implies the prerequisite of a paired account and the scope of results, but there is no explicit when-to-use guidance or pointer to the relevant alternative (e.g. wa_list_group_members for participant-level detail, wa_get_chat for a single group).

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

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

Goes well beyond readOnlyHint/idempotentHint=false: it discloses result ordering, how to page with next_cursor, that calling twice yields the same empty page (explaining the non-idempotent hint), and that include_history switches the page to storage order rather than time order. That last point is a subtle behavioral trap an agent would otherwise miss.

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 scope and ordering, then paging, then use case, then filters, then the polling caveat. No filler; each sentence carries a distinct operational fact.

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?

An output schema exists, so return-field documentation is unnecessary, and the description still names next_cursor because it is needed to drive paging. For an 8-parameter, zero-required list tool this covers everything an agent needs to call it and poll correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning: since/until are keyed to when the message was SENT and until is exclusive, and include_history changes the sort order so results must be re-sorted by 'at'. Useful clarification over identical schema text.

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 plus the scope that matters most: 'Read messages across all your accounts — WhatsApp and Telegram — oldest first.' The oldest-first ordering and multi-account default immediately separate it from single-message siblings like wa_get_message.

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

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

Gives a concrete use case ('catch up after being notified of a new message'), the polling cadence ('wait about 30 seconds'), and narrowing options. It stops short of naming when NOT to use it — e.g. wa_get_message or wa_list_channels — so the exclusion half of the guidance is implied 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?

The annotations already declare readOnlyHint=true and idempotentHint=false. The description adds useful behavioral context beyond annotations: it explains returned review statuses, rejected_reason on rejected templates, and that templates only apply to Business numbers, not personal linked-device numbers.

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 and status detail are front-loaded, and the later sentences carry useful downstream usage and scope-exclusion information. The second sentence is dense and could be split for readability, but no sentence is wasted.

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

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

With a fully documented single parameter, read-only annotations, and an output schema, the description gives everything else an agent needs: what is listed, status meanings, downstream usage with wa_send_message, and the Business-number-only scope. Return-value details can safely live in the output schema.

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

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

There is one parameter and schema description coverage is 100%; the schema already documents account_id as the Business account returned by wa_list_accounts. The description adds that the account must be a Business (Cloud API) number rather than a personal linked-device number, but this is not parameter-specific meaning beyond the schema baseline.

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: list WhatsApp Business message templates for a Business (Cloud API) number, including review status. It also distinguishes the resource from personal linked-device numbers, so an agent can tell what this tool is for.

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 clear usage context: use an APPROVED template's name and language with wa_send_message to message outside the 24-hour window, and pass the variables count as template_variables in order. It also excludes personal linked-device numbers, but it does not explicitly contrast this listing tool with siblings like wa_create_template or wa_delete_template.

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 only say it writes, is non-idempotent and non-destructive; the description adds the real behavioral facts: the phone must be online, it usually answers within seconds, loaded messages never trigger webhooks, and they fall inside the plan's history window. That is exactly the context an agent needs before invoking.

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

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

Four short sentences, front-loaded with the action and the online requirement, followed by how to read the result and the retention semantics. 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?

Covers the offline/latency caveat, the webhook-invisibility caveat, the visibility flag needed elsewhere, retention, and the prerequisite. With an output schema and annotations present, nothing an agent needs is missing.

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

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

Schema coverage is 100% – chat format, count range/default and account_id fallback are all documented in the schema. The description adds only lightweight framing ('one conversation', 'before the oldest one stored'), so baseline 3 applies.

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

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

States a specific verb and resource: fetch older messages for one conversation from the account's phone and store them. The phrase 'before the oldest one stored here' precisely distinguishes it from wa_list_messages and wa_get_chat, which only read what is already stored.

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

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

Gives concrete routing: read the result with wa_get_chat using the same chat, and load with include_history=true to see it in wa_list_messages. It also names the prerequisite (at least one stored message to page back from). It does not explicitly say when not to call it (e.g. when the phone is likely offline), but the context is clear.

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 only declare the non-read-only, non-idempotent, non-destructive profile; the description adds substantial context beyond that: QR re-arms roughly every 20 seconds and the newest must be shown, phone codes last a few minutes, Telegram two-step verification flips state to password_needed with the password entered on the console pairing page and never through a tool, and Telegram accounts must be enabled for the workspace or the call is refused. These are operational traits an agent cannot infer 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 core instruction ('ASK FIRST' plus the two-linking-methods branch) is front-loaded, and the sentence about polling and state transitions comes after. It is dense and long, but nearly every clause carries a rule the agent must apply; a small amount of the QR/phone description could be trimmed given the schema.

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?

Covers everything needed for a pairing tool: which inputs to pass in which situation, the Telegram constraints, the follow-up polling behavior, timing windows, and the terminal 'paired' state. Return values are partly described (QR PNG, pair_code, pair_id) and an output schema exists, so nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already carries format details. The description still adds decision-level meaning by tying phone to the single-device case and import_history to choosing whether WhatsApp history loads, though it largely restates what the schema fields say rather than extending them.

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 ('Begin linking a new WhatsApp account') and immediately qualifies the scope with the Telegram variant ('or a Telegram account, with network set to telegram'). This clearly separates it from wa_pair_status (polling) and wa_unpair_account (teardown) without the agent needing to open sibling 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?

Gives an explicit decision procedure: 'ASK FIRST', then branch on whether the user can scan a QR from another screen versus having only one phone. It names the alternative call path (pass phone for a code), the Telegram-only path, and the required follow-up ('Then poll wa_pair_status with the returned pair_id'), so both when-to-use and what-comes-next are spelled 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?

Adds context the annotations can't carry: the non-idempotent character (new image returned on each call, so show the latest) and the security-relevant 'password_needed' path where the user must enter their cloud password on the console page, never in this tool. It does not mention whether pair_id expires or how long pairing sessions live, which is the main remaining behavioral unknown.

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

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

Four short, front-loaded sentences that map cleanly onto state branches; no filler. Slightly dense, but each sentence carries actionable information and the ordering follows the agent's decision flow.

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?

An output schema exists, so return values needn't be enumerated, yet the description still explains the meaningful state values and how to act on each. Combined with the password-handling caveat, an agent has enough to call and interpret this correctly; only session lifetime/polling cadence is missing.

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

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

Schema description coverage is 100% and the single parameter's schema text ('the pair_id returned by wa_pair_account') already carries the full meaning. The description only repeats the provenance of pair_id, adding no format or constraint detail beyond the schema.

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

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

Opens with a specific verb and resource ('Check a pairing started with wa_pair_account'), and immediately ties itself to the sibling that starts the flow, so an agent can distinguish the initiate step from the poll step without opening either schema.

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

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

States the precondition (a pairing started with wa_pair_account) and gives per-state instructions: show the latest image while 'qr', show pair_code while 'code', and treat 'paired' as readiness signalled by wa_list_accounts. It stops short of telling the agent how often to poll or when to give up, which is a real gap for a polling tool.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so safety is partly covered. The removal-by-empty-string behavior is genuinely useful context, but it is duplicated verbatim in the reaction parameter's schema text, and nothing is said about visibility to other participants or the channel limitation documented only in the schema.

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

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

Two short sentences, front-loaded with the core action and followed by the one non-obvious modifier. 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?

With a complete input schema, an output schema and annotations present, the description only needs to nail purpose and the removal semantics, which it does. Minor gaps (channel-message restriction, group `sender` requirement) are covered by the schema rather than the description.

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

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

Schema description coverage is 100%, so all five parameters (including the tricky group-only `sender` and the `account_id` fallback) are already fully documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline.

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 (react) and resource (a WhatsApp message) plus the emoji detail, which cleanly separates it from message-sending siblings like wa_send_message. It never names a sibling for comparison, so it stops short of full 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 second sentence usefully explains how to undo a reaction (empty string), which is a real usage cue. But there is no explicit when-to-use/when-not guidance, no mention of prerequisites (e.g. channel messages unsupported) and no pointer to alternatives such as wa_send_message or wa_delete_message.

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 this as destructive and non-idempotent. The description adds useful behavioral context by stating the admin permission requirement, which is not captured in the annotations. It stops short of explaining failure behavior or edge cases, so it is strong but not exhaustive.

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 two short sentences with the action and prerequisite front-loaded. There is no wasted 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?

For a destructive group-membership mutation, the description covers the core action and the required admin privilege, while annotations cover the safety profile and the output schema covers return values. It is largely complete, though it could mention edge-case behavior for removal failures.

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 parameters are already well documented. The description mentions phone number or JID for members, but it largely repeats what the schema provides and adds little beyond it.

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

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

The description states a specific verb and resource: remove members from a WhatsApp group. It is clear what the tool does, but it does not explicitly distinguish itself from sibling tools such as wa_update_participants or wa_leave_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?

It includes an important prerequisite that the account must be a group admin, which helps usage. However, it does not state when to use this tool instead of alternatives or describe exclusions, so the guidance 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 declare a non-read-only, open-world, non-idempotent, non-destructive call, but not what happens to the payload. The description adds that the report is emailed to the team along with the workspace and the sender's address, so a reply reaches the person by email, and it sets a privacy boundary (no passwords, keys, unshared message contents). It doesn't mention rate limits or duplicate-submission behavior, so not a 5.

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

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

Four sentences, front-loaded with purpose then usage then content then safety; each sentence does work. The privacy sentence is slightly tacked-on but is genuinely necessary for a tool that forwards user text externally.

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 an output schema, full parameter documentation and annotations present, the description only needed to add routing, behavioral destination and content expectations — and it does all three. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantic content beyond the field docs: it prescribes writing in the person's words and enumerates the structure a bug report should contain (what was done, what happened, what was expected, error text), which goes past the schema's shorter phrasing.

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 bug report, feature request or feedback about WhatsMCP to the WhatsMCP team') and explicitly contrasts with the nearest sibling, wa_send_message. An agent can route between the two without opening either schema.

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

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

Gives both the trigger ('when the person asks to report a problem, suggest a feature or leave feedback') and the exclusion ('not to contact a WhatsApp user (that is wa_send_message)'). Coverage guidance ('write it in the person's words') further shapes correct use.

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

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

With only readOnly/idempotent/destructive hints from annotations, the description adds critical behavioral context the annotations cannot convey: the meaning of 'sent', 'queued' (accepted but not confirmed — do NOT resend), and 'refused' (nothing sent, reason indicates retry viability). It also discloses per-attachment size limits and caption behavior, which directly affect how the agent should call it.

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 core action and modes, then details, then status semantics. It is dense but earns most of its length given 15 parameters and multi-backend behavior; a few phrases overlap with the schema.

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 complex, high-parameter-count mutation tool, the description covers the essential modes, restrictions (template windows, size limits), and the crucial return-status handling. An output schema exists, so the extra status explanation is bonus rather than a gap-filler.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail, setting the baseline at 3. The description reinforces the attachment parameters (sizes, caption semantics) but adds little beyond what the schema already states.

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 ('Send a message from one of your accounts'), enumerates the supported message modes (text, image, document, audio, template), and covers both WhatsApp and Telegram backends. It is clearly distinguishable from siblings like wa_edit_message, wa_list_messages, and wa_create_template.

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 strong usage context: template for Business numbers is 'the only way to start a conversation or to message that number outside the 24-hour window', and status handling tells the agent not to resend on 'queued'. However, it doesn't explicitly compare against alternatives such as wa_edit_message for corrections or wa_react for reactions.

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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false; the description adds real value beyond them by disclosing 'fire-and-forget: there is no delivery confirmation.' It does not mention presence expiry or rate limits, which are the remaining behavioral unknowns for a presence 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?

Two tight sentences: the capability/state vocabulary comes first, then the fire-and-forget caveat. No filler and nothing to trim.

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, a complete input schema, and an output schema present, the description covers what an agent needs to call it correctly. Minor gaps (account defaulting behavior, how long a presence state persists) are not blocking given the structured fields.

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 'state' values and the conditional role of 'chat' are already documented in the schema; the description largely restates the enum vocabulary. Baseline 3 applies since the schema carries the parameter 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 specific verb (announce/set) with the two distinct resources it acts on: a chat's typing state and the account's online presence, enumerated with concrete values. An agent can immediately tell this is not a messaging tool like wa_send_message, though no sibling is named explicitly.

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

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

It gives a clear usage rule: 'chat' is required for composing/paused and ignored for available/unavailable, which tells the agent which mode to pick. It lacks explicit exclusions or a pointer to alternatives (e.g. use wa_send_message to actually deliver a message), keeping it below a 5.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, yet the description still adds real context: irreversible deletion ('previous photo cannot be restored'), server-side transformations (center-cropped to square, max 640x640), and propagation delay for contacts. This is behavior an agent would otherwise have to guess.

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 effect and target, then the two modes, then the consequences. Slightly redundant with the schema on image format and cropping, but every sentence carries operational meaning and there is 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?

An output schema exists, so return values need no explanation; the description covers what is left: ownership constraint, both invocation modes, irreversibility, and the caching behavior after success. Nothing an agent needs to avoid a wrong call is missing.

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

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

Schema coverage is 100%, so format, size and mutual-exclusion rules are already documented in the parameter descriptions; the description largely restates them. It adds only mildly, by framing the two modes as alternatives in prose. Baseline 3 applies.

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

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

States a specific verb and resource ('Change the profile photo') and scopes it to the caller's own account with 'the picture every contact sees'. That distinguishes it cleanly from the read-only sibling wa_get_profile without needing to name 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?

Gives explicit branch conditions: pass image_base64 to replace, or remove=true to delete, which is a clear either/or usage rule. It does not name the read-side sibling (wa_get_profile) or state exclusions at the account level, so it stops just short of a 5.

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

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

Goes well beyond the annotations: it discloses that the call is non-idempotent in a consequential way ("Calling this again replaces the endpoint and issues a NEW secret") and that the returned signing secret is shown only once and must be stored immediately. That is exactly the operational context an agent needs before invoking a mutation, and it does not conflict with readOnlyHint=false or idempotentHint=false.

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

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

Three sentences, front-loaded with the core action, then defaults, then the destructive replacement warning. Every sentence carries distinct information with no 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 two-parameter mutation with full schema coverage and an output schema, this covers everything material: what it does, the default event scope, the security-sensitive return value, and the overwrite behavior. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it states the default event behavior (inbound messages only) and groups the optional events into outbound, delivery status, lifecycle, and call categories. It doesn't restate the events array enum values, but the schema already enumerates them fully.

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

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

Starts with a specific verb+resource ("Register an HTTPS endpoint to receive WhatsApp events") and immediately scopes the effect (events arrive as they happen rather than by polling). It is trivially distinguishable from wa_get_webhook, wa_delete_webhook, and wa_enable_webhook, which share the resource but not the action.

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

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

Gives a clear motivating context ("so you do not have to poll wa_list_messages") and warns about the replacement semantics of a repeat call. It stops short of naming the sibling tools for inspecting or removing an existing webhook, so the agent must infer that wa_get_webhook/wa_delete_webhook are the alternatives for those needs.

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 non-idempotent, and the description adds real context beyond that: sending and receiving stop immediately, message history survives, and recovery requires re-pairing via a new code scan. It does not address what happens on a repeated call or whether unpairing an already-unpaired account errors, leaving the idempotency caveat only implied by 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?

Three short sentences, each carrying distinct information: what happens, what is preserved, what recovery costs. The caution comes last as a natural call to action, 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?

An output schema exists, so return values need no explanation. For a one-parameter destructive operation the description covers consequences, data retention, reversibility, and the confirmation requirement — everything an agent needs to decide and act.

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

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

There is a single required parameter with 100% schema coverage, and the schema already tells the agent the account_id comes from wa_list_accounts. The description adds nothing further about the parameter, so baseline 3 applies.

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

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

States a specific verb (disconnect) and resource (a WhatsApp or Telegram account from this service), and implicitly separates itself from wa_pair_account by noting that re-connecting requires pairing again. An agent can identify the operation and its scope without opening the schema.

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

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

Gives an explicit precondition for use – confirm with the user before calling, because the action is not trivially reversible. It does not name the sibling wa_pair_account as the counterpart operation directly, and gives no when-not guidance, so it falls just short of a full 5.

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

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

Goes well beyond the annotations by disclosing that changes are applied individually and that a refusal returns an 'applied' list of the changes that took effect before it — a failure-mode detail an agent cannot infer from readOnlyHint/idempotentHint/destructiveHint. It also states the admin-permission prerequisite, which no annotation conveys.

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?