whatsmcp

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

Annotations declare readOnlyHint=true and idempotentHint=false, but the description adds substantial context beyond them: the exact refusal mode (plan_required), where to check eligibility (wa_get_plan), the lifecycle status values, the fact that summary/transcript/collected data only appear after the call ends, and that recording_url expires in one hour. The expiry TTL and partial-result behavior are exactly what an agent needs and cannot get from the schema or 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 availability caveat is front-loaded and the payload sentence is dense but single-purpose with no filler. The second sentence is long — a status list, six return fields, and a TTL in one breath — which slightly hurts scanability but wastes no 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?

An output schema exists, so return values did not need spelling out, yet naming them (plus the one-hour recording validity) is genuinely useful. Combined with the prerequisite, refusal mode and eligibility pointer, 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% and the single parameter already documents 'from wa_ai_call_start'; the description restates the same origin rather than adding format or validation detail. With the schema doing the work, 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 an AI call started with wa_ai_call_start) and enumerates exactly what comes back: status values, summary, success judgement, collected data, transcript, and recording_url. An agent can distinguish this from wa_ai_list_calls 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?

The prerequisite is clear (call_ref comes from wa_ai_call_start) and the caveat routes the agent to wa_get_plan for plan discovery. However, it never says when to prefer this over enumerating with wa_ai_list_calls, and the bracketed 'not usable in this workspace' note leaves the agent unsure whether to call it at all versus skipping straight to the sibling.

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 a non-read-only, destructive, idempotent operation; the description adds real substance on top: the hangup is immediate for both parties, an already-ended call is left alone and returns hung_up false, and post-call artifacts (summary, transcript, recording) still arrive. It also discloses the plan_required refusal mode and points at wa_get_plan.

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 availability caveat and then the core action, with no filler sentences. The bracketed workspace note is somewhat long but is high-value routing information, so it 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 exist, so return-shape explanation is unnecessary; everything else an agent needs — availability precondition, effects on both parties, idempotent no-op behavior, and follow-up read path — is present.

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

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

Only one parameter, and schema description coverage is 100% — the schema already says call_ref comes from wa_ai_call_start or wa_ai_list_calls. The description repeats the same provenance without adding format or edge-case 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 and resource — end a live AI voice-agent call — and scopes it to both agent-started calls (wa_ai_call_start) and agent-answered incoming calls. It is clearly distinguishable from wa_ai_call_get (read results) and wa_ai_call_start (begin a call).

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 the operative condition (there is a live call to end) and routes result-reading to wa_ai_call_get and plan-checking to wa_get_plan, plus a workspace availability caveat. It does not spell out an explicit 'do not use this if…' exclusion beyond the plan note, so it is a strong 4 rather than 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 only declare non-read-only, non-idempotent, non-destructive; the description adds substantially more: asynchronous immediate return with a call_ref, the poll cadence and terminal statuses, the result payload contents, one-call-at-a-time-per-number plus a post-call cooldown, and the recipient_not_contact guard with its force override and WABA exception. It also discloses the workspace-level plan_required refusal, which is the single most important behavior for an agent to know 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?

Front-loading the 'not usable in this workspace' caveat is exactly right, and every sentence carries information: purpose, workflow, constraints, safety guard. The cost is a dense single paragraph of roughly 130 words with several semicolon-chained clauses, which could be broken into bullets for faster scanning.

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 asynchronous, side-effecting tool this is complete: it explains the immediate return, how to follow up, what the terminal statuses are, what the result contains, and the concurrency/cooldown limits. An output schema exists so return values need no further explanation, and the description covers everything an agent needs to call and then correctly follow up.

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 fully documented, including the force guard and the variables example. The description reinforces the key ones ('Pass per-call context in variables', preset from wa_ai_list_presets) but adds little syntax or semantics the schema does not already carry. 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: have an AI voice agent call a WhatsApp number from one of your numbers using a named preset. It distinguishes itself from the related siblings by naming wa_ai_list_presets (source of the preset), wa_ai_call_get (the polling counterpart) and wa_get_plan (the plan lookup). An agent can tell exactly what this tool is versus wa_ai_call_get or wa_ai_call_hangup.

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 and when-not-to-use: it first warns the tool returns a plan_required refusal in this workspace and points to wa_get_plan. It then spells out the full call lifecycle ('Returns immediately with a call_ref... Poll wa_ai_call_get about every 30 seconds until status is done, failed, no_answer or busy') and the alternatives for continuing the workflow.

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 readOnlyHint/idempotentHint, but the description adds substantial behavior: newest-first ordering, the direction/from semantics, that inbound calls depend on a preset's answers_inbound flag, and the plan_required refusal path via wa_get_plan. This is rich context beyond structured fields.

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

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

The caveat is front-loaded and every sentence carries information, but the opening bracket about plan_required is verbose for what is a conditional prerequisite. Still dense and largely waste-free.

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, return values needn't be explained, and the description still covers direction, from, call_ref handoff, pagination, and the plan limitation. An agent has everything needed to call 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 both limit and before are fully documented in the schema. The description reinforces before as a call_ref-based pagination token but adds little beyond what the schema already states; 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 this workspace's AI voice-agent calls') and scopes it to outbound calls started with wa_ai_call_start plus inbound calls answered by answers_inbound presets. This clearly distinguishes it from the sibling wa_list_calls (which handles non-AI calls).

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: pairs a call_ref with wa_ai_call_get for transcript/recording, and warns to consult wa_get_plan for the plan_required refusal. It names alternatives but doesn't explicitly state when to prefer wa_list_calls over this one, leaving that inference to the agent.

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 real behavioral context the annotations cannot: calling it returns a plan_required refusal in this workspace, readiness is exposed via ready/not_ready_reason, and presets carry expected_variables. The opening caveat and the subsequent description of normal listing behavior pull in opposite directions, which costs a point on coherence even though the disclosure itself is valuable.

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 definition and the wa_ai_call_start routing are front-loaded and efficient, but the bracketed preamble is dense and delivers a mixed message before the reader knows what the tool is. Three of the four sentences earn their place; the caveat could be a single clear clause.

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

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

An output schema exists, so return values need not be spelled out, yet the description still explains ready/not_ready_reason and expected_variables enough to act on. The only completeness gap is that it never resolves the tension between 'not usable in this workspace' and the normal listing instructions.

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 4 applies. The description's discussion of ready and expected_variables refers to returned fields rather than inputs, so it neither helps nor hurts here.

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

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

The core sentence is a specific verb+resource ('List the AI voice-agent presets') and it goes further by defining what a preset is (voice agent + WhatsApp line + default variables), which distinguishes it from wa_ai_list_calls. The bracketed preamble saying it is 'Not usable in this workspace' muddies the stated purpose and makes the agent wonder whether the tool is callable at all.

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 routes clearly downstream: use the preset's name with wa_ai_call_start, pass expected_variables there too, and only presets with ready=true can call now. It also points to wa_get_plan for per-number plan information. What it lacks is an explicit statement of when to consult presets versus the sibling wa_ai_list_calls/wa_ai_call_get tools.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds real behavioral context beyond them: the effect on the target ('can no longer call or message it') and exactly what the response reports (number, address-book name, country). It doesn't discuss reversibility nuances or whether a repeated block is a no-op, which is relevant given 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?

One front-loaded sentence that leads with the primary action and then the inverse flag. The trailing return-value clause is somewhat redundant given an output schema exists, but it is brief and harmless.

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

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

For a three-parameter mutation with full schema coverage, full annotation coverage, and an output schema, nothing an agent needs to invoke it correctly is absent. The account_id reference to wa_list_accounts is carried by the schema.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema itself. The description's explanation of unblock largely restates the schema wording and adds no new format or edge-case detail, 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 ('Block a contact on one of your WhatsApp accounts') and covers the inverse mode explicitly ('set unblock=true to unblock one'). This is clearly distinguishable from the read-only sibling wa_list_blocked, which lists rather than mutates block state.

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

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

The dual-mode usage is spelled out: default blocks, and unblock=true reverses it. What's missing is guidance on prerequisites or when to prefer a sibling (e.g., wa_list_blocked to check current state first), so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the mutation profile is covered. The description adds one genuinely useful behavioral note — that the returned JID feeds wa_send_message's 'to' — but says nothing about whether members are added immediately or invited, what happens on duplicate creation, or any permission/account prerequisites.

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, front-loaded with the action and followed by the return-value/routing hint. 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?

With an output schema present and full schema coverage, the description only needs to orient the agent, which it does, including the downstream JID usage. Slight gap: no mention of account pairing/prerequisite state or member-invitation behavior for a non-idempotent write.

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% (E.164/JID formats, 25-char limit, 'do NOT include your own number', account_id from wa_list_accounts), so the schema carries all parameter meaning. The description only restates 'a name and initial members from one of your accounts' and adds nothing beyond it.

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

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

States a specific verb and resource ('Create a WhatsApp group') plus the two inputs that define it (name, initial members, source account). The verb alone separates it from wa_update_group, wa_join_group, and wa_delete_group, 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?

Usage is implied by the verb — an agent knows to call this when it needs a new group rather than joining one — but there is no explicit when-to-use/when-not guidance and no mention of wa_join_group as the alternative for existing groups.

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/write/idempotency profile; the description adds the missing behavioral context an agent needs — that submission triggers an asynchronous external review with variable latency, and that the template is unusable until approval. This is exactly the value-add beyond 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?

Front-loaded with the action and the review caveat, and every clause carries a constraint. The middle section is a fairly dense run-on stacking categories, variable ordering and number scoping, which slightly taxes scanning.

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 11-parameter mutation tool whose return values are covered by an output schema, the description supplies the lifecycle context (review, approval gating), the naming/variable conventions and the account scoping. Nothing essential for a correct call is left to inference.

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 goes further by explaining the coupling between body variables {{1}}, {{2}} and body_examples (one example per variable, in order, read by reviewers) and by restating the category enum. It doesn't cover header/header_example or call_permission constraints in prose, but the schema does.

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

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

The description names a specific verb and resource ('Submit a new WhatsApp Business message template') plus the scope constraint ('on one of your Business (Cloud API) numbers'), which separates it cleanly from siblings like wa_delete_template or wa_list_templates.

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 states the preconditions explicitly: templates can only be sent via wa_send_message's template option after wa_list_templates shows APPROVED, and it restricts applicability to Business numbers. Alternatives and their selection conditions are named, not implied.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds genuinely non-obvious behavior: there is no true group-delete, so the call empties the group and exits, plus an admin authorization requirement. The main gap is failure semantics — nothing says what happens if a member removal fails mid-way or if the caller is not an admin.

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, and the operative behavior is front-loaded before the caveat. The 'no true group-delete' clarification earns its place because it corrects a likely false assumption.

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

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

With annotations covering destructiveness and an output schema covering return values, the description supplies the two things structure doesn't: the admin prerequisite and the real-world semantics. Only partial-failure behavior is left unaddressed for what is inherently a multi-step mutation.

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

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

Schema description coverage is 100%, with both group_jid and account_id documented including cross-references to wa_list_groups and wa_list_accounts. The description adds no parameter-level 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 a specific verb and resource ('Delete a WhatsApp group') and immediately explains the mechanism: remove every other member, then leave. That composite definition implicitly distinguishes it from wa_leave_chat and wa_remove_participants, so an agent can tell which operation it is 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 a real precondition ('the account must be a group admin') but never says when to prefer this over wa_leave_chat or wa_remove_participants, nor when not to use it. Usage is implied by the operation description rather than stated as routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is set. The description adds real value beyond that by explaining the mechanism: this is a server-side revoke, not a local wipe, and modern clients honour it – important for setting expectations about what happens on the recipient's device. It stops short of saying the action is irreversible or that it can be refused by clients/old versions.

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 then the one nuance that matters. No filler, nothing buried.

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

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

For a simple, well-schema'd mutation with an output schema and destructive annotations, the description covers the essential what and how. The only gap is operational framing – reversibility, permission requirements, or failure modes – which an agent might want before issuing 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 description coverage is 100%, so the schema already documents all four parameters including the group/admin nuance on `sender` and the account fallback on `account_id`. The description adds nothing parameter-specific, 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+resource plus scope: 'Delete a WhatsApp message for everyone.' It doesn't explicitly name a sibling (e.g. wa_edit_message) as the alternative, but the intent is unmistakable and the 'for everyone' scope sets it apart.

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 rather than stated – an agent infers this is the tool for removing a message already sent. There is no explicit when/when-not guidance, no mention of the edit-vs-delete choice, and no note that deletion is usually for one's own message or requires admin rights (that only appears in the schema for `sender`).

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the cascade behavior when `language` is omitted and the external side effect that Meta blocks name reuse for a period — both non-obvious consequences of deletion.

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

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

A single sentence with zero filler, front-loading the action and scope, then appending the cascade rule and the Meta name-block caveat. Nothing is redundant.

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 carry the safety profile, so the description only needs to convey scope and consequences — which it does. It could go slightly further on irreversibility or confirmation expectations for a destructive bulk (all-language) deletion, but the essentials for correct invocation are present.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the omit-to-delete-all semantics for `language`. The description restates that semantics but adds no new syntax, format, or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (Delete) and resource (WhatsApp Business message template) scoped to a Business (Cloud API) number, and immediately disambiguates cascade behavior (one language vs. all languages of the name). This clearly separates it from siblings like wa_create_template and wa_list_templates.

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 the key decision — omit `language` to delete every language of the name — and warns that Meta blocks reuse of the deleted name for a while, which helps an agent decide whether to call it now. It does not explicitly name alternatives (e.g., prefer this only when the template is truly unwanted vs. wa_create_template for a new one), so it stops short of full when/when-not guidance.

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

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

Annotations already flag destructiveHint=true, but the description adds genuinely new behavioral facts: what survives the operation ('messages keep arriving and stay readable through wa_list_messages'), and that calls fail with a plan_required refusal in this workspace. That is exactly the kind of blast-radius and failure-mode context 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?

Two sentences plus a bracketed caveat, all of which earn their place, and the blocking caveat is front-loaded so the agent reads it before anything else. The bracket is dense and could be split, but nothing is redundant.

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

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

With no parameters, an output schema present, and destructive/read-only hints supplied by annotations, the description covers the only remaining unknowns: whether the tool is callable here, what failure looks like, and what data is preserved.

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?

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly avoids inventing parameter detail.

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 effect: 'Stop delivering inbound messages to the configured endpoint,' which an agent can immediately map to the webhook resource. It does not explicitly name wa_enable_webhook / wa_set_webhook as the counterparts, but 'only the push stops' clearly separates it from message deletion.

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 bracketed note is an unusually explicit when-NOT-to-use: it says the tool is unusable in this workspace, that calling it yields a plan_required refusal, and routes the agent to wa_get_plan for per-number plans. The only gap is that no positive 'use this when...' alternative (e.g. wa_set_webhook to repoint the endpoint) is offered.

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

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

The description adds a genuine behavioral constraint the annotations do not carry: WhatsApp only accepts an edit within roughly 20 minutes of the original send. That tells the agent to expect a failure mode for old messages. It stops short of saying what the response or error looks like when the window has passed.

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 padding. The core action comes first and the constraint follows, so it is front-loaded and proportionate to a simple mutation tool.

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

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

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. The time-window caveat is the one thing an agent could not infer elsewhere. Only minor gap is silence on the failure behavior once the window lapses.

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 every parameter is documented in-schema, so the schema does the work. The description adds no format or syntax detail about chat, message_id, or the replacement text. 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?

"Edit a WhatsApp message you sent" is a specific verb+resource and the ownership qualifier ("you sent") narrows scope usefully. It naturally separates from wa_send_message, wa_delete_message and wa_react in the sibling list, though it never names them explicitly.

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

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

The 20-minute window implies when the call will succeed, which is real guidance, but there is no explicit when-to-use/when-not and no fallback named for the expired case (e.g., send a new message, or the delete path). Usage 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?

Annotations already say idempotent=true and destructive=false, but the description adds real behavior: the endpoint and signing secret survive a pause, and messages keep arriving and stay readable via wa_list_messages. It also discloses the plan_required refusal mode, which is behavior no annotation carries. Slightly short of 5 only because the refusal/workspace caveat is conveyed as a parenthetical rather than a clean precondition statement.

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 critical caveat is front-loaded and each sentence does work — non-destructive semantics, the delete/recreate alternative, and the paused-message behavior. The bracketed workspace note is long and em-dash dense, costing a bit of scannability.

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

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

An output schema exists, so return values need not be explained. For a state-toggle tool the description covers availability preconditions, what is preserved, what happens to inbound messages, and the sibling alternative — everything needed to call it correctly or avoid calling it.

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

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

Schema coverage is 100% and both parameters are already described there, including the true/false meaning of enabled and the optional note semantics. The description reinforces the non-destructive semantics of the toggle but adds no syntax or format detail 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 pair (pause/resume) and resource (webhook delivery) and immediately scopes it: 'WITHOUT changing the endpoint or its signing secret.' That contrast is exactly what separates it from wa_delete_webhook and wa_set_webhook in the sibling list, despite the enabling-sounding tool name.

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

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

Gives an explicit when-to-use-plus-alternative: use this to stop deliveries temporarily, because deleting and re-creating the webhook would issue a new secret. It also flags that the tool is unusable in the current workspace and routes the agent to wa_get_plan for per-number plan eligibility.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the mutation profile is covered. The description adds only that it is account-scoped and link-driven, but says nothing about the practical consequence of the non-idempotent flag (what happens on a repeat follow) or any rate limits.

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

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

A single front-loaded sentence with no filler and the action stated first. The phrase "from one of your accounts" slightly duplicates the account_id parameter, but overall it is tightly scoped.

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 two parameters are fully documented. What is missing for a non-idempotent mutation is the expected outcome when the follow is repeated or fails, which an agent would need before invoking.

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

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

Schema coverage is 100% and both parameters explain themselves, including the accepted link format and the cross-reference to wa_list_accounts. The description adds no meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb (Follow) and resource (WhatsApp Channel) plus the key input (its link), so an agent can distinguish it from wa_join_group or wa_list_channels. It stops short of explicitly naming those siblings, which keeps it from a 5.

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

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

"from one of your accounts using its link" implies the prerequisites, but the description never states when to use this versus wa_list_channels or wa_join_group, nor what to do if the channel is already followed. Usage is implied rather than guided.

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, so safety is covered structurally. The description adds genuine behavioral detail beyond that: results are ordered oldest-first, and one conversation's results include older history brought in by wa_load_history. It does not discuss result density or ordering caveats across chats, so it is useful but not rich.

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

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

The primary behavior and the 'chat' variant are front-loaded in the first clause, with guidance and filtering after. It is tight overall, though the em-dash stacking makes the opening sentence slower to parse than it needs to 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?

With an output schema present, return-shape explanation is unnecessary, and the description covers account scoping, conversation scoping, time bounds and the sibling alternative. Minor gaps (limit behavior, media URL opt-in) are fully handled by the schema, so 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%, so every parameter is already documented in detail, including the exclusive 'until' boundary and the 1h signed media URL. The description only reiterates that since/until refer to send time and that until is exclusive, which duplicates rather than extends 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 for one account) plus a clearly bounded variant (one conversation when 'chat' is supplied), including that history loaded via wa_load_history is visible. The scope distinction against wa_list_messages is made explicit, so an agent can choose 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 affirmative use case ("for context before replying") and names the alternative tool with its selecting condition ("use wa_list_messages to page through everything new"). It also states how to narrow results with since/until, leaving nothing to inference about which tool fits.

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 real behavioral context beyond the annotations: the admin permission requirement and the consequence of reset=true (revocation plus reissue). One tension is left unaddressed — revoking an existing link invalidates it for everyone who holds it, yet destructiveHint is false; the description could have clarified that this is a link rotation rather than data loss.

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, with the primary read operation front-loaded and the mutating variant plus prerequisite following. Nothing is repeated or padded.

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

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

An output schema exists, so return values need no explanation, and the admin prerequisite plus reset behavior cover the main invocation risks. Minor gaps remain, such as what happens when the caller is not an admin or when the group has no link yet.

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 group_jid, account_id, and reset are already fully documented, including the cross-references to wa_list_groups and wa_list_accounts. The description restates the reset semantics without adding format or edge-case 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 and resource ('Get a WhatsApp group's invite link') and immediately covers the mutation variant via reset=true. It is clearly distinguishable from neighbors like wa_update_group, wa_list_groups, and wa_create_group.

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 condition for the alternative mode ('set reset=true to revoke it and issue a new one') and a hard prerequisite ('must be a group admin'). It does not name a sibling tool as an alternative, but no sibling overlaps enough to require routing guidance.

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

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

Goes well beyond the readOnlyHint/idempotentHint annotations by disclosing the size-dependent return contract: small attachments arrive as base64 in media_base64, large ones as a time-limited media_url to GET separately. It also defines the 'refused' failure semantic, which is the kind of thing an agent otherwise discovers only by trial.

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: what it fetches, how the payload varies by size, and the failure case. Front-loaded with the core action and free of repetition or 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 an output schema present the description need not document return fields, yet it still covers the branching payload shape and the refusal case. Combined with annotations and full schema coverage, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so both parameters are already documented, including the account_id omission rule and the Telegram id format. The description reinforces that message_id comes from wa_list_messages but adds no syntax or format detail the schema lacks, 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 (fetch) and resource (the attachment a received message carried), and enumerates the media kinds covered, so an agent knows this is binary retrieval rather than message text. It never names the obvious sibling wa_get_message, leaving the attachment-vs-message-body distinction implicit.

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 prerequisite chain by telling the agent to use the message_id from wa_list_messages, and pre-empts the most likely confusing outcome by defining what 'refused' means. No explicit when-not-to-use or named alternative is provided.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=false, so the safety profile is covered. The description adds useful framing: single-record retrieval rather than a scan, and the webhook-as-source workflow that motivates the call. It stops short of saying what happens if neither key is supplied or if the message is missing, which is the remaining behavioral 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?

A single front-loaded sentence with the key constraint ('ONE', the two lookup keys) first, followed by a use case. No restatement of the name or title and 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 full output schema, 100% schema coverage, and read-only annotations, an agent has everything needed to invoke this correctly. The description supplies the workflow context the structured fields cannot, and nothing material 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%, including the 'pass this or message_id/cursor' exclusivity and the one-hour media URL lifetime, so the schema does the heavy lifting. The description repeats the message_id provenance (webhook delivery or wa_list_messages) rather than adding new meaning, 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 and resource ('Fetch ONE stored message') and pins down the two lookup keys (message_id or cursor). It explicitly contrasts itself with paging through history, i.e. wa_list_messages, so an agent can route correctly without opening either schema.

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

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

It names concrete trigger scenarios — reading the message a webhook reported, or the one about to be reacted to, edited, or deleted — and states the negative case (no paging through history). That is explicit when-to-use guidance with an implied alternative (wa_list_messages) for the bulk case.

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?

Well beyond the readOnlyHint annotation, it explains the non-obvious mechanics: excluded_tools lists only what no active number can use in workspace mode, plan becomes "mixed", and a tool invoked without account_id must be permitted on every active number. Those rules are exactly the failure modes an agent would otherwise misread.

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 purpose, then scope, then diagnostic use cases, with zero filler. Some sentences are long and clause-heavy (the excluded_tools and no-account_id rules), costing a little readability, but nothing is redundant.

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 one-parameter read-only tool with an output schema; the description still covers mode semantics, refusal implications, and the incidental server_version report. 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 already 100%, but the description adds the consequence of each mode — one number's plan and its excluded_tools versus the workspace intersection and "mixed" plans — which the schema's one-line parameter note does not convey.

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 ("Show a plan, its limits and current usage") and immediately scopes it to WhatsApp numbers vs. the whole workspace. No sibling tool deals with plans or limits, and the description makes that boundary obvious.

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 trigger conditions: call it to diagnose plan_required errors, refusals of wa_send_message, or to check remaining headroom. It also spells out the choice between the two modes — pass account_id for one number, omit for the workspace — with no inference required.

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

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

Annotations cover read-only safety, and the description adds real behavioral context the annotations cannot: results are account-relative, and an empty about/picture means the peer withheld it from this account rather than that it is unset. It does not cover failure behavior for unregistered numbers beyond the registered flag, so it falls short of a 5.

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

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

Two sentences: the first front-loads what is returned, the second delivers a high-value caveat about empty fields. No repetition of the title or schema, nothing 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 an output schema present, return values need not be restated, and the description covers scope and the main interpretive pitfall. It leaves implicit that phone is effectively the key input (the schema marks nothing required), a minor gap for a lookup 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 coverage is 100%, including phone format and the account_id lookup path, so the baseline is 3. The description adds only the soft notion of per-account visibility, not new semantics for either parameter.

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

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

States a specific verb (look up) and resource (a phone number's WhatsApp identity) and enumerates exactly what comes back: registration status, public name, about text, picture, and business categories/contact/hours. This is clearly distinguishable from sibling list tools like wa_list_contacts and from 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?

"From one of your accounts" implies the account_id scoping and the schema points to wa_list_accounts, but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as wa_get_chat for numbers already in a chat. Usage is inferable 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?

Beyond the readOnlyHint annotation, the description discloses important behavior: the workspace-level plan_required refusal, the inclusion of disabled reason, and the crucial fact that the signing secret is never returned. These are meaningful operational details an agent could not infer from annotations alone.

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 critical workspace limitation is front-loaded in brackets, followed by two focused sentences covering return content and secret handling. Every sentence earns its place with no filler.

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

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

An output schema exists, so the description need not explain the response shape. It still covers the key caveats an agent needs—plan refusal, disabled reason, and secret exclusion—making the definition complete for this read-only 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 has zero parameters, so there is nothing for the description to clarify beyond the schema. Baseline score of 4 is appropriate for a no-parameter tool.

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 and resource: 'Show the currently configured inbound webhook,' and clarifies what is returned (enabled status, disabled reason). It is clearly distinct from sibling mutators like wa_set_webhook, wa_delete_webhook, and wa_enable_webhook.

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 states the tool is not usable in this workspace and that calling it returns a plan_required refusal, then routes the agent to wa_get_plan as the alternative. This is unambiguous when-not-to-use guidance with a named sibling.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive mutation. The description adds only that an invite link is used and that it operates from one of the user's accounts; it does not explain failure modes, already-member behavior, or whether the account must be paired first.

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 with zero waste. It states the action, resource, and mechanism immediately.

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

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

An output schema exists and annotations cover mutation traits, so the definition is minimally callable. However, for a write operation it omits useful context such as whether the account must be paired, what happens if already a member, and what a successful join returns.

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

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

Schema description coverage is 100%, so both parameters are already documented with usage hints ('as returned by wa_list_accounts' and invite-link format). The description adds no meaning beyond 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 ('Join a WhatsApp group') and names the required mechanism ('using its invite link'). It is clear enough to distinguish from wa_create_group and wa_leave_chat, though it does not explicitly name those siblings or state that it is not group creation.

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 only the basic action, with no explicit when-to-use guidance, prerequisites (e.g., account must be paired), or alternatives such as wa_create_group or wa_get_group_invite_link. An agent gets implied usage from the invite-link mention but no routing guidance.

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

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

The description clarifies *what* is being modified (group membership/channel subscription), which adds functional context. However, the primary behavioral safety (destructive nature) is handled by the annotations, limiting the description's added value in this category.

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 maximally concise, providing the full scope of the tool's function in a single, highly efficient sentence. The structure is perfectly front-loaded.

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 simplicity of the input schema and the presence of strong annotations (destructive, not read-only), the description provides all necessary context for a successful initial tool call decision.

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 schema description coverage is 100%, setting a baseline of 3. The description reiterates that the JID and account_id are the necessary arguments, but adds no specific semantic nuance beyond the schema's provided definitions.

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 clear verbs ('leave', 'unfollow') and identifies the resource scope ('group' or 'channel'). It is highly specific about the tool's function and avoids ambiguity.

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

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

The purpose itself serves as the primary guideline. By specifying 'leave' or 'unfollow', it naturally excludes the use of tools like 'join' or 'follow'. It is clear about when this operation is required.

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 safety is covered; the description instead adds the non-obvious usability rule that an account is only usable while state is 'connected' (status 'live') and that status/what_to_do carry the diagnosis. It does not address any rate limits or what an empty account list means, but the state gating is real behavioral context beyond 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?

Three sentences, front-loaded with purpose then immediately the usage rule. The middle sentence is dense with em-dashes but every clause carries a decision rule; nothing is redundant filler.

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

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

An output schema exists, so return values need not be enumerated, and the description still names the salient fields an agent must act on (state, status, what_to_do). For a zero-parameter read tool, this is complete enough to call correctly on the first attempt.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is closed (additionalProperties: false) and fully covered. Baseline 4 applies, with no parameter-level gap.

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

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

States a specific verb and resource ('List the WhatsApp accounts') plus scope ('available to you'), which cleanly separates it from the many wa_list_* siblings over messages, groups, contacts and templates.

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 trigger ('only when no message row gives you the account_id'), two concrete scenarios (first message to an unknown number, diagnosing a broken account), and an explicit exclusion ('when replying, reuse the row's account_id'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context: it explains the returned fields (number, address-book name with absence caveat, country) and discloses that WhatsApp does not report block dates.

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 sentences, front-loads the core purpose, then efficiently adds return-field semantics and the block-date limitation. Every sentence earns its place.

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

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

For a simple read-only listing tool with a complete input schema, existing output schema, and safety annotations, the description is complete: it covers purpose, returned fields, and the notable absence of block-date data.

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

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

Schema description coverage is 100%, so the single account_id parameter is already well documented in the schema. The description does not add further semantics or formatting details beyond what the schema provides, matching the baseline of 3.

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

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

The description uses a specific verb and resource: 'List every contact one of your accounts has blocked.' The scope ('blocked') clearly distinguishes it from sibling tools like wa_list_contacts and wa_block_contact.

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 purpose—reading an account's blocklist—but the description does not explicitly state when to use this tool versus alternatives such as wa_list_contacts or wa_block_contact.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=false), yet the description adds real behavior: oldest-first ordering, the explicit paging loop with next_cursor/has_more, and that each call reports answered status and duration. It omits account/auth prerequisites and rate-limit or result-size caveats.

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 tight sentences, front-loaded with the resource and ordering, then paging, then record contents, then filtering. No sentence is redundant and every one 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?

With an output schema present and full parameter coverage, the description only needs to explain usage, which it does for paging, filtering, and ordering. The missing piece is disambiguation from wa_ai_list_calls, which matters given the dense sibling set.

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, including until being exclusive. The description reinforces the exclusive-until rule and the after_cursor paging contract but adds little syntax or interpretation 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 call history') plus scope ('across your WhatsApp accounts') and ordering ('oldest first'). It does not differentiate from the close sibling wa_ai_list_calls, so an agent cannot be certain which list tool to pick without opening both 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?

Clearly explains operational usage: paginate with after_cursor/next_cursor until has_more is false to export the full history, and narrow with since/until. It stops short of when-not guidance or naming alternatives such as wa_ai_list_calls or wa_list_messages.

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, so the safety profile is covered. The description adds the returned fields, but it does not explain pagination, limits, or why the operation is marked non-idempotent.

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

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

It is a single front-loaded sentence with no wasted words. The scope and return fields are stated immediately.

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

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

For a simple read-only list tool with an output schema and full parameter documentation, the description is nearly complete. It could mention pagination or result limits, but those gaps are minor given the structured metadata.

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 account_id parameter is already documented as the account whose channels to list. The description reinforces the account scoping but adds no syntax or format 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?

The description states a specific verb and resource: list channels followed by one account. It also names the returned fields, so an agent can distinguish it from wa_follow_channel and other list tools without opening the schema.

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

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

The usage is implied by 'channels one of your accounts follows,' but there is no explicit when-to-use guidance, no exclusions, and no named alternative such as wa_follow_channel or wa_list_accounts.

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 safety is covered. The description adds real behavioral context beyond that: include_pictures triggers per-contact lookups on WhatsApp, capping pages at 10 and making the call slow, and it recommends leaving it off for a fast listing. It does not describe pagination/cursor behavior explicitly, which is the 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?

Four sentences, each containing distinct information: channel semantics, identifier routing, query matching, and the picture-lookup cost. It is dense but front-loaded and free of filler; the picture caveat is partly redundant with the schema's own description, slightly diluting the tightness.

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 covers the channel-dependent meaning of the results and the cost tradeoff. For a read-only listing tool with four optional parameters this is close to complete; only explicit cursor/paging guidance 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 cross-channel meaning the schema does not: query matches on Telegram also by username, and include_pictures is WhatsApp-only with the page cap consequence restated in context. The after_cursor parameter is left entirely to the schema.

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

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

States a specific verb and resource ('List or search the address book of one of your accounts') and immediately differentiates what the resource means per channel (WhatsApp phone contacts vs Telegram saved contacts plus chat partners). An agent can tell this apart from siblings like wa_list_accounts or wa_list_blocked without opening the schema.

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

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

Explicitly routes the agent downstream: use returned phone numbers with wa_send_message, use each row's jid as 'to'/'chat' with every other tool. It also gives the conditions for query and include_pictures. It does not say when to prefer this over adjacent listing tools such as wa_list_blocked, which keeps it short of a 5.

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

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

Annotations already establish readOnlyHint=true, so safety is covered. The description adds genuinely non-obvious return semantics: phone number surfaces in a field named 'name', and each item carries a JID and an 'admin' flag — a quirk an agent would otherwise get wrong. It says nothing about ordering, pagination, or behavior on large groups, which keeps it off 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, purpose first, then the return-shape detail. Every clause carries information an agent would not get from structured fields alone; no filler.

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

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

For a read-only, two-required-param tool with a full output schema and complete schema coverage, the description covers purpose and the main return quirk. Minor omission: no mention of member ordering or what happens for very large groups, but nothing blocks a correct call.

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

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

Schema description coverage is 100%, so both parameters (group_jid, account_id) are already fully documented, including the @g.us format and cross-references to wa_list_groups / wa_list_accounts. The description adds nothing about parameters beyond 'group's members', 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 ('List a group's members'), which is immediately distinguishable from wa_list_groups and from mutating siblings like wa_remove_participants or wa_update_participants. It stops short of explicitly naming a sibling to contrast against, so it sits just below the top band.

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

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

The description gives no when-to-use or when-not guidance and no prerequisites. The only routing hint ('as returned by wa_list_groups') lives in the schema parameter description, not in the tool description itself.

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 scope ('groups one of your accounts has joined') and return fields, but does not explain idempotentHint=false, ordering, or freshness of the member count.

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

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

A single sentence with no filler. The core purpose and return fields are front-loaded, and every phrase contributes useful 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?

The tool is simple, has one fully documented parameter, read-only annotations, and an output schema. The description is sufficient to call it correctly, though it could be stronger by naming the sibling member-listing tool or clarifying ordering/freshness.

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 account_id description already explains that the value comes from wa_list_accounts. The tool description repeats the 'one of your accounts' idea but adds no further parameter semantics beyond the schema.

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

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

The description states a specific verb and resource: list groups for one account, including JID, name, and member count. It distinguishes listing groups from creating/updating/deleting them, but does not explicitly distinguish this from the sibling tool wa_list_group_members.

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 'one of your accounts has joined' and the account_id schema note pointing to wa_list_accounts. However, there is no explicit when-to-use guidance or mention of the alternative wa_list_group_members for member-level listing.

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 readOnlyHint and non-idempotency; the description adds substantial behavior: chronological vs. storage ordering when include_history is on, how next_cursor/after_cursor paging works, that a repeat poll returns the same empty page, and that media URLs are 1-hour signed GET links. This is exactly the operational context an agent cannot infer from 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?

Front-loaded with what the tool does and how to page, then narrowing filters, then polling advice — a sound information order with little waste. A few clauses echo the schema verbatim (e.g., 'until is exclusive'), which trims a point.

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 eight-parameter, all-optional read tool with an output schema covering return shape (including next_cursor), the description covers paging, filtering, ordering side effects, and polling cadence. Nothing material is missing 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?

Schema coverage is already 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema lacks: passing back the prior next_cursor, and the caveat that include_history flips page ordering so results must be sorted by 'at'. It does restate some schema-level facts (until is exclusive), so it stops short of a 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 and resource ('Read messages'), the scope ('across all your accounts — WhatsApp and Telegram'), and the ordering ('oldest first'). An agent can immediately tell this apart from single-message siblings like wa_get_message or account-scoped siblings like wa_list_accounts.

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 trigger ('Use this to catch up after being notified of a new message') and a polling discipline ('when a poll finds nothing new, wait about 30 seconds'). It also routes away from wa_get_media for attachment bytes via the include_media_urls parameter.

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 context annotations can't: the three possible review statuses, that rejected templates carry Meta's rejected_reason, and that templates only exist for Business numbers. It doesn't need to describe the return shape since an output schema exists.

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

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

Front-loads the purpose and statuses before the workflow tip, and every sentence carries information. It is dense but slightly overpacked, folding status enumeration, send-workflow, and account-type caveat into one run-on block rather than separate scannable sentences.

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-param read tool with an output schema and readOnly annotations, the description covers scope, return semantics, downstream usage, and the personal-vs-business distinction. An agent has everything needed to call it and to know what to do with the result.

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 account_id is already documented as coming from wa_list_accounts. The description reinforces the 'Business (Cloud API) number' meaning but adds no format or syntax 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 (List) and resource (WhatsApp Business message templates) scoped to a Business (Cloud API) number, plus what each item carries (review status, rejected_reason). It explicitly distinguishes from personal linked-device numbers, which eliminates a real ambiguity an agent could hit.

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 the exact downstream workflow: use an APPROVED template's name and language with wa_send_message's template/template_language, and pass its variables count as template_variables in order. It also states the trigger condition (starting a conversation or messaging outside the 24-hour window) and the exclusion for personal numbers.

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 substantial context beyond the annotations: the phone must be online, latency is usually seconds, loaded messages never trigger webhooks, and retention follows the plan's history window. This explains the non-idempotent, mutating nature (remote fetch + local store) that readOnlyHint=false only implies.

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 action and its precondition, and every sentence carries information (latency, webhook suppression, retention, read path). Slightly dense at five sentences, 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 the description covers the operational requirements (phone online), side effects (webhook suppression), retention, and the follow-up read call. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents chat, count (1-500, default 50), and account_id. The description only restates 'in one conversation' and 'older messages' without adding format or edge-case semantics, 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: asks the account's phone for older messages in one conversation, before the oldest stored one, and stores them. This is clearly distinct from wa_list_messages and wa_get_chat, which are named explicitly as the read paths.

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 the triggering condition (paging back before the oldest stored message) and the prerequisite (the conversation needs at least one stored message). It also routes the agent to the follow-up tool ('Read the result with wa_get_chat') and flags that wa_list_messages only shows loaded messages with include_history=true.

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 non-read-only, non-idempotent, non-destructive, which says almost nothing about this interactive flow. The description adds substantial operational detail beyond them: a re-arming QR every ~20 seconds, a phone code valid 'a few minutes', a password_needed state for Telegram two-step verification (with the password entered on the console page, never via a tool), and the transition to 'paired'.

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

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

Front-loaded with the purpose and then the decision rule, and nearly every clause is decision-relevant. It is a single dense paragraph rather than clearly segmented branches, which costs a point on structure, but there is little pure 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 not be explained, yet the description still tells the agent what comes back (QR PNG, pair_code, pair_id) and how to continue. Timing lifetimes, terminal state, and the password_needed exception complete the flow an agent needs to drive 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 each parameter already carries a rich description, so the description mostly restates the same rules (phone in international format, telegram enables QR-only, import_history for WhatsApp history). It adds marginal value by framing phone absence as the QR trigger, but not enough to exceed the baseline when the schema already does the work.

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

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

Opens with a specific verb and resource ('Begin linking a new WhatsApp account — or a Telegram account'), and the scope covers both networks in one sentence. It is plainly distinguishable from siblings like wa_pair_status and wa_unpair_account, which are named or implied elsewhere in the text.

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 instructs to ASK FIRST, then branches on user device constraints: QR when another screen is available, phone code when the user has only the one phone ('it cannot scan its own screen'). Telegram is scoped to QR only and the polling handoff to wa_pair_status is stated outright.

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=true and idempotentHint=false; the description explains why the latter holds (a new image is returned each time while in "qr"), which is exactly the context annotations cannot convey. It further discloses the password_needed branch and the state transition to "paired", giving real behavioral guidance beyond the flags.

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, each mapped to a distinct state or action, with the primary instruction (check the pairing) front-loaded. No redundant restatement of the title or 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?

Output schema exists so return values need not be re-explained, yet the description still enumerates every state the caller must handle and the correct user-facing action for each. Nothing an agent needs to poll correctly and act on the result 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 pair_id parameter is fully documented in the schema (100% coverage) as "the pair_id returned by wa_pair_account", and the description merely references the same origin. No additional format, lifetime, or reuse semantics are added, so the schema does the work and 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 and resource ("Check a pairing started with wa_pair_account") with an explicit link to the initiating sibling, which no other sibling tool covers. An agent can distinguish it from wa_list_accounts and wa_pair_account 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 per-state instructions for each value: for state "qr" show the latest image, for state "code" show pair_code, for "password_needed" the user acts on the console's pairing page. It also states an explicit exclusion ("never here") and the terminal condition ("paired" → visible in wa_list_accounts).

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 non-read-only, non-idempotent, non-destructive; the description adds real behavioral context beyond that — an empty string removes a reaction, and the phrasing 'a reaction you previously sent' scopes removal to your own reactions. It does not mention error behavior or the channel limitation, so it stops short of full disclosure.

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 core action is front-loaded and the non-obvious removal trick follows immediately. Nothing here needs trimming or reordering.

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, an output schema, and 100% parameter coverage already in structured fields, the description only needs to frame the action and the removal case, which it does. The one gap is the unsupported-channel constraint, which an agent would only discover by reading the chat parameter 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 non-obvious group-only sender and the account_id defaulting rule) are already documented in the schema. The description only restates the reaction/empty-string semantics that the schema also covers, adding no new parameter meaning.

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

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

States a specific verb (react) and resource (a WhatsApp message) plus the payload (an emoji), and adds the inverse operation (empty reaction removes). No sibling tool covers reactions, so an agent can route here without ambiguity against wa_send_message, wa_edit_message, or wa_delete_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?

The removal case is spelled out clearly, which is genuine usage guidance, but the description never names an alternative or states when not to use this tool. It also omits the channel restriction (reacting to @newsletter messages is unsupported), which lives only in the schema and is exactly the kind of routing constraint that belongs here.

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 destructive=true, readOnly=false, idempotent=false; the description adds the admin-permission requirement, which is real behavioral context not encoded in structured fields. It leaves out what happens on partial failure or with non-member inputs.

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, the action and its scope front-loaded, prerequisite second. No filler and nothing redundant.

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?

Output schema exists so return values need not be explained, and annotations carry the safety profile. With the admin prerequisite and identifier formats covered, the definition is nearly complete; only error/partial-failure behavior is unaddressed for this destructive operation.

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

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

Schema coverage is 100% and each parameter already carries a description (members format, group_jid source, account_id source). The description only restates that members may be phone numbers or JIDs, adding nothing 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?

Names a specific verb and resource ('Remove members from a WhatsApp group') and adds the accepted member identifiers (phone number or JID), so the action is unambiguous. It does not distinguish itself from the close sibling wa_update_participants, which would have earned a 5.

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

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

States a concrete precondition — the account must be a group admin — which tells the agent when the call can succeed. It stops short of naming alternatives (e.g. wa_update_participants or wa_list_group_members for verification) or when not to use it.

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

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

Goes beyond the annotations by disclosing the real side effect and its destination: the report is emailed to the team along with the workspace and the sender's address, so a reply reaches the person by email. It also adds a data-handling constraint (never include passwords, API keys or unshared message contents), which annotations do not express. It does not mention rate limits or duplicate-submission behavior, so it stops short of a 5.

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

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

The core purpose and the sibling exclusion are front-loaded in the first two sentences, and the later sentences each add non-redundant rules (email routing, bug template, privacy). It runs five sentences and could be tightened, but 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?

For a three-parameter write tool that has an output schema, the description covers everything needed to call it correctly: trigger conditions, the sibling to avoid, where the report goes, what metadata is attached automatically, how to compose the body, and what must never be included.

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 telling the agent how to fill the message field for bugs (what was done, what happened, what was expected, error text) and by imposing a content exclusion rule that no schema constraint expresses. It adds writing guidance rather than restating field names.

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

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

States a specific verb and resource ('send a bug report, feature request or feedback about WhatsMCP') and immediately distinguishes itself from the sibling that could be confused with it ('not to contact a WhatsApp user (that is wa_send_message)'). An agent can route between the two without inspecting 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 names the triggering conditions ('when the person asks to report a problem, suggest a feature or leave feedback') and names the excluded alternative with the condition that selects it. Both the when and the when-not are present.

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: discloses the recipient_not_contact refusal gate, the 24-hour Business window constraint, per-attachment size limits, caption behavior, and the meaning of each returned status including a warning against retrying queued sends (consistent with idempotentHint=false). This is exactly the extra context annotations cannot convey.

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

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

Front-loaded with purpose and dense enough that nearly every clause carries information; length is justified by 16 parameters. It suffers slightly from being one long run-on paragraph with repeated force/limit statements that also appear in 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 16-parameter mutation tool with an output schema, the description covers everything an agent needs: recipient id conventions per backend, attachment constraints, the contact gate, template rules, and status interpretation. No meaningful gap remains 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?

Schema coverage is 100%, so baseline is 3, but the description adds real semantic grouping: the three mutually exclusive attachment types with their limits, template overriding text/attachments, and force having no effect on groups/channels/templates/Business/Telegram. Some of this duplicates schema text, but the cross-parameter interactions are new value.

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

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

Opens with a specific verb+resource ('Send a message from one of your accounts') and immediately enumerates the media variants and Telegram backend case. It is clearly differentiable from siblings like wa_edit_message, wa_react, 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?

Gives concrete when-to-use conditions: templates for starting conversations or messaging outside the 24-hour window, force for non-contact recipients, and explicit 'do NOT send it again' on queued status. It names sibling tools (wa_list_accounts, wa_list_messages) for obtaining ids, though it does not route the agent away from this tool toward edit/react for modifying existing messages.

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, and the description adds real context beyond them: 'fire-and-forget: there is no delivery confirmation,' which tells the agent not to retry or wait on a result. It does not mention rate limits or whether the recipient actually sees the state, so it falls short of fully rich behavioral disclosure.

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 dual-mode capability first, then the fire-and-forget caveat. Every clause carries information an agent needs, with no repetition or 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 an output schema present, return values needn't be described, and annotations cover the safety profile; the description covers both operational modes and the lack of delivery confirmation. Only minor gaps remain, such as how long a typing state persists and whether presence is visible to other participants.

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

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

Schema coverage is 100% — the chat, state, and account_id parameters are each documented, including the conditional requirement of chat for composing/paused. The description largely restates what the schema already says about the two state modes and adds no syntax, format, or account_id resolution details, so baseline 3 applies.

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

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

The description names a specific verb (announce/set) and two distinct resources (typing state in a chat, account online status), and enumerates the concrete state values for each mode. No sibling tool in the list deals with presence, so an agent can unambiguously attribute this capability here; the only missing element for a 5 is an explicit statement about how it relates to siblings.

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

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

It gives clear context for when each mode applies — typing announcements go to a chat, availability applies to your own account — and indirectly clarifies that no alternative tool exists for this. There is no explicit 'do not use this for X' guidance, but nothing about the intended usage is left ambiguous.

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 genuinely new context: the previous photo cannot be restored, the image is center-cropped and capped at 640x640, and contacts may see a stale photo until their app refreshes. That irreversibility and eventual-consistency detail is exactly what an agent needs before calling.

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

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

Front-loaded with the core action, then mode selection, then consequences — a sensible ordering with no filler. It repeats some schema-level detail (5 MiB ceiling, 640x640 scaling), which is defensible for critical constraints but keeps it from being maximally tight.

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

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

With an output schema present, return values need no explanation, and annotations cover the safety profile. The description completes the picture with irreversibility, image transforms, and caching behavior, leaving nothing an agent needs missing for a 3-parameter 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 parameter descriptions already state formats, size limits, cropping and the remove/image_base64 mutual exclusion. The description largely restates those facts, adding only the 'as WhatsApp stores it' framing, 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+resource ('Change the profile photo') scoped to 'one of your own WhatsApp accounts' and clarifies it is the picture contacts see. This cleanly separates it from read-only siblings like wa_get_profile and from contact-level operations.

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 documents the two operating modes — supply image_base64 to replace, or remove=true to delete — which is the main decision an agent faces. It does not explicitly name a sibling alternative (e.g. wa_get_profile to inspect the current photo first), so it falls short of a full when/when-not rubric.

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: discloses the plan_required refusal and workspace limitation, the one-time signing secret, and that re-calling replaces the endpoint and issues a NEW secret — the key consequence of idempotentHint=false. Default event scope (inbound only) is also disclosed. Minor tension with destructiveHint=false since existing config and secret are overwritten, but this is disclosed rather than contradicted.

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 workspace/plan caveat is front-loaded in brackets before the core behavior, which is the right priority, and every sentence carries information (default scope, event taxonomy, secret handling, replacement semantics). It is dense but not padded; the bracketed note is slightly long relative to the rest.

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, the description need not detail return values, yet it still flags the one-time secret that matters operationally. Combined with the URL reachability requirement, event defaults, and plan limitation, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that omitting events yields inbound messages only and that each event category maps to outbound messages, delivery status, lifecycle, and call events. This lets an agent choose events without reverse-engineering the enum list.

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

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

States a specific verb and resource: registers an HTTPS endpoint to receive WhatsApp events, explicitly framed as an alternative to polling wa_list_messages. The sibling set contains wa_get_webhook, wa_delete_webhook, and wa_enable_webhook, none of which are named or distinguished here, so an agent must infer how 'set' relates to 'enable'.

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 use case (receive events as they happen instead of polling) and a hard exclusion (returns plan_required in this workspace, check wa_get_plan). It does not address when to prefer wa_enable_webhook or what happens if a webhook already exists beyond 'calling this again replaces the endpoint'.

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 (destructiveHint=true) by specifying the concrete consequence: sending and receiving stop immediately, message history is preserved, and reversal costs the user a re-pairing scan. That is exactly the pre-call context an agent needs before an irreversible-feeling action.

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 consequence, ending with the safety instruction. 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?

A destructive mutation with a documented output schema and strong annotations; the description covers state change, data retention, reversibility, and the confirmation requirement. 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% and the schema already documents account_id including its source ('from wa_list_accounts'). The description adds only the account-type context (WhatsApp/Telegram) and nothing about the identifier's format, 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 ('Disconnect') and resource ('a WhatsApp or Telegram account'), plus the scope ('from this service'). The clause about re-connecting requiring pairing implicitly distinguishes it from wa_pair_account, so an agent can route correctly.

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 behavioral guidance: 'ask the user before calling this' because re-connection requires a new pairing code. It does not name the counterpart sibling (wa_pair_account) explicitly, but the scenario is unambiguous.

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