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

Annotations already declare read-only, idempotent, non-destructive, and open-world behavior. The description adds useful context beyond them by noting the recipient is not notified and that a JID is returned for each number, though it omits edge behavior for unregistered numbers and 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?

Three sentences, front-loaded with the purpose, followed by usage guidance and a safety note. Every sentence earns its place with no redundancy.

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

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

For a simple read-only batch check, annotations and schema cover most needs, and the description adds the JID return and non-notification behavior. It does not fully specify the response shape for numbers not registered on WhatsApp, which is a minor gap without an output schema.

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

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

Schema coverage is 100%, so the schema already documents the numbers array format, country-code requirement, max 50, and optional instance_id. The description adds only that one or more numbers are accepted, which is minor 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: checks whether phone numbers are registered on WhatsApp and returns the JID for each. It also distinguishes the tool from sending siblings by explaining its role before sending.

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

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

It gives clear usage context: use before sending to a number you are not sure about to avoid failed sends. It does not explicitly state when not to use it or name an alternative tool, but the guidance is actionable.

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 non-read-only, idempotent, non-destructive and open-world, so safety is covered; the description adds the crucial behavioral fact that 'The user must complete the step on their phone', which no annotation conveys. It still doesn't say whether the call blocks until connected, returns immediately, or must be polled via get_instance_status.

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

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

Three dense sentences with the core behavior front-loaded before the mode detail and the user-action caveat. The WhatsApp menu breadcrumb is slightly verbose but earns its place by making the pairing-code flow unambiguous.

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

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

There is no output schema, yet the description never says what comes back — a QR payload, a pairing code string, or just a status — nor whether the agent should poll get_instance_status afterward. For a two-mode connection tool that gap matters, though the workflow trigger and user-side instruction are well covered.

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 documented there, including 'Omit to get a QR code instead' and the instance_id fallback. The description's 'international format, digits only' largely restates the schema's 'digits with country code', so it adds little beyond the baseline.

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

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

States a specific verb and resource ('Starts the WhatsApp connection of an instance') and clearly splits the two modes: QR without `phone`, pairing code with `phone`. It doesn't differentiate itself from the sibling get_qr_code, which appears to overlap with the no-`phone` path, so an agent still has to guess which of the two to use for QR retrieval.

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 triggering condition: 'Use when get_instance_status shows disconnected', naming the sibling to check first. It also warns the flow is not fully programmatic. There is no explicit when-not guidance (e.g. what to do if already connected, or when to prefer get_qr_code).

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 tell the agent this is a non-read-only, non-idempotent, open-world write. The description adds genuinely operational context: the calling instance becomes admin, participants are added and notified immediately, the 50-participant cap, and the concrete ban/report risk. This is exactly the kind of behavior that is invisible in 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 tight sentences, front-loaded with the action and constraints, followed by the safety rationale. Every sentence earns its place and there is no redundant restatement of structured fields.

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

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

There is no output schema, and the description does not say what is returned (e.g., group id/JID) on success or what happens with invalid numbers. Otherwise it is complete for a mutation tool: constraints, side effects, and risk are all covered.

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 contributes meaning beyond the schema by explaining that instance_id (the instance number) becomes the group admin, and it reinforces the participant limit and name length constraints in operational terms. A small gap remains around phone-number formatting, which is covered only by the schema.

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

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

Opens with a specific verb and resource ('Creates a group with the given participants') and immediately discloses the key side effect that the instance number becomes admin. It is clearly distinguishable from siblings like list_groups, get_group_info, and manage_group_participants.

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

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

Provides strong situational guidance around participant consent ('only add people who agreed') and the ban risk of unsolicited adds. It does not explicitly compare against alternatives such as manage_group_participants or state prerequisites like needing a connected instance, so it falls 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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the description is not carrying the safety burden alone. It still adds value beyond the annotations by disclosing the scope ('for all participants') and the ownership constraint (only instance-sent messages), which the annotations do not express. It stops short of stating failure modes such as attempting to delete a message outside the platform's deletion window or a message already deleted.

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, zero redundancy, and the highest-stakes fact (irreversible, affects all participants) is placed early. Nothing could be removed without losing an instruction the agent needs.

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

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

With no output schema, the description would normally need to cover return behavior, but for a deletion call the meaningful gap is narrower: what happens on failure (message too old, not owned by the instance). The ownership and authorization rules are present, so an agent can decide correctly; only the error path is unstated.

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

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

Schema description coverage is 100% and every parameter is documented in the schema itself, so the baseline of 3 applies. The description only indirectly hints at instance scoping via 'sent by this instance' and adds no syntax or format guidance for message_id or the optional number.

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 (deletes), resource (a message sent by this instance), and blast radius (all participants of the chat), which cleanly separates it from the sibling edit_message. An agent can distinguish it from every other send_/react_/edit_ tool without opening the schema.

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

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

Gives an explicit precondition ('only works on messages the instance itself sent') and an explicit authorization gate ('use only on explicit user request'), which is exactly the guardrail needed for an irreversible action. No sibling alternative is named, but none is applicable 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 declare destructive=true, idempotent=true, openWorld=true, so the bar is lower; the description still adds real value by disclosing the recipient-visible 'edited' marker and the edit-window/time limit, neither of which is in the structured data. It does not spell out that the original text is replaced irreversibly, which is the main behavioral trait left implicit.

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

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

Three tight clauses, zero filler: the operation, the recipient-visible effect, the two hard constraints, and the usage rule. The scope constraint is front-loaded in the first sentence.

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

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

For a 4-parameter mutation with annotations covering safety and a fully described schema, the description supplies the operational constraints an agent needs (own-message only, edit window, user intent). Only the return value is unspecified, a minor gap given no output schema exists.

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

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

Schema description coverage is 100% and every parameter (number, message_id, text, instance_id) is documented in the schema with format hints, so the description's silence on parameters is acceptable. It adds no meaning beyond the schema, which is the baseline case.

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 (edits the text of a previously sent message) and scopes it to messages sent by this instance, which cleanly separates it from send_text and delete_message. The user-visible consequence ('recipient sees an edited mark') further pins down what the operation actually does.

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

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

It gives an explicit when-to-use rule ('Use only when the user asks to correct a message') plus two when-not constraints: messages must be sent by this instance and must still be inside WhatsApp's edit window. It stops short of naming a fallback (delete_message or send_text) for when the edit window has closed, so the routing is clear but not fully closed.

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, idempotentHint, and destructiveHint=false, so the safety profile is carried structurally. The description adds genuine value beyond that: default sort order ('newest activity first by default') and pagination via limit/offset. It stops short of describing max result behavior or total counts, but the added context is real.

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 with no filler: purpose plus filters first, then return shape and ordering, then the intended use case and pagination. Front-loaded and every clause carries information.

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

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

For an 8-parameter read-only search with no required params and no output schema, the description covers filters, return shape, ordering, and pagination, and the schema handles instance_id fallback. The only real gap is the phantom 'label' filter, which is a correctness issue rather than missing context.

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?

Description names most filter dimensions (name, group, archived, blocked, pinned) matching schema properties, and the schema supplies descriptions for the key ones. However, it advertises a 'label' filter that does not exist in the input schema at all — a mismatch that could mislead an agent into passing an unsupported parameter.

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

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

States a specific verb and resource ('searches the instance's chats'), enumerates the filter dimensions, and describes the return ('chat ids and metadata'). The clause 'Use to find the chat id/number of a conversation before reading its messages' cleanly separates it from the sibling find_messages.

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

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

Explicitly names the workflow context — find the chat id before reading messages — which is the main reason an agent would pick this over find_messages. It does not address alternatives such as list_groups for group enumeration, but the primary routing decision is covered.

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/idempotent/non-destructive, and the description still adds real value beyond them: it flags that message content is untrusted third-party text with a never-follow-instructions rule, and it states the pagination model (limit/offset). The prompt-injection warning is exactly the kind of context annotations cannot carry.

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

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

Four short sentences, front-loaded with the return value, then scoping, then routing, then the safety caveat and pagination. No sentence is redundant and nothing repeats the schema verbatim.

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

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

With no output schema, the description correctly states what is returned and how to page through it, and it covers the safety posture. It does not state result ordering (newest first vs oldest) or the default page size, which matter for a history tool, so it falls just short of complete.

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

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

Schema coverage is 80% and the schema already documents limit, chat_id, message_id, and instance_id in more detail than the description. The description adds only the pagination hint for limit/offset and the scoping intent, which is marginal; offset remains undocumented anywhere. 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 ('Returns messages of the instance') plus the two scoping filters (chat_id, message_id), which cleanly separates it from find_chats and from the send/react/edit/delete siblings. An agent can pick this over find_chats 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?

'Use to read a conversation or to get message ids for react/edit/delete' gives both the read path and a concrete downstream workflow, implicitly routing to react_to_message/edit_message/delete_message. No explicit when-not or exclusion (e.g. vs find_chats) is stated, 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so 'Read-only' in the description is largely redundant. The description does add useful context by listing exactly which account data is exposed (balance, billing day, status), which helps the agent judge whether the call answers its question. It does not cover rate limits, auth requirements, or failure modes.

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

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

Two sentences, no filler, and the returned-field list is front-loaded so an agent immediately knows what data it gets. The trailing 'Read-only' is the only near-redundant element.

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

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

With no output schema, the description carries the burden of describing the return payload, and it does so explicitly by naming every field. For a no-argument read tool this is fully sufficient 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?

The tool takes zero parameters, so there are no parameter semantics to explain and the baseline is 4. Schema coverage is 100% and the description does not need to compensate.

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

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

States a specific verb and resource ('Returns the ZapZap account') and enumerates the fields returned: name, email, balance, billing day, status. No sibling tool touches account-level data, so an agent can distinguish it from the instance/message/webhook/group tools at a glance.

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

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

Gives two concrete use cases: verifying that credentials work, and checking balance sufficiency before creating or renewing instances. That is clear positive guidance. There is no explicit when-not section, but no sibling competes for the same job, so the omission is minor.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so 'Read-only' is redundant. However, the description adds a genuine behavioral disclosure beyond the annotations: the invite link is sensitive because anyone holding it can join the group. That is real risk information an agent needs before setting include_invite_link=true.

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, each carrying distinct information: what is returned, the optional sensitive field with its risk, and the safety profile. Front-loaded with the return payload and 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 no output schema, the description usefully enumerates returned fields, and it covers the one optional parameter with its default and risk. Missing are error behavior for invalid or non-member groups and any note on instance requirement, which keeps it short of complete.

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

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

Schema coverage is 100%, so group_jid, instance_id and include_invite_link are already documented, giving a baseline of 3. The description adds the security consequence of include_invite_link, but says nothing extra about instance_id resolution or JID format beyond the schema.

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

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

States a specific verb and resource ('Returns a group's name, description, participants, admins, creation date and settings'), which fully specifies what comes back. It does not distinguish itself from the nearby sibling list_groups, so an agent must infer the difference between listing groups and reading one group's details.

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 required group_jid and the returned fields, but there is no explicit statement of when to prefer this over list_groups or when the invite link should be requested. No prerequisites (e.g. instance connection) are stated either.

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, idempotentHint and destructiveHint=false, so 'Read-only' adds nothing. However, the description contributes context annotations cannot: the causal consequence that messages will fail when status is not 'connected' and which tools to use in that case. It does not cover auth or rate-limit behavior, but for a polling status check that is minor.

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 what is returned, followed by the conditional guidance. The trailing 'Read-only' is the only low-value clause, but it is a short tag rather than noise.

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

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

No output schema exists, so the description compensates by naming the returned fields (status, phone number, profile name). Combined with the failure-mode guidance and the fully documented single parameter, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and the schema already explains the optional instance_id, the ZAPZAP_INSTANCE_ID fallback, and the list_instances prerequisite. The description adds nothing about parameters, so baseline 3 applies.

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

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

States a specific verb+resource ('Returns the instance's connection status') and even enumerates the possible status values. Clearly distinguishable from siblings like get_qr_code or connect_instance, which are named as follow-ups.

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

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

Explicitly says when to use it ('Use before sending') and routes to alternatives under a stated condition ('if not connected ... use get_qr_code or connect_instance'). 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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real value beyond them: ~1 minute QR expiry, the need to re-call after expiry, and the alternative response when already connected. It also gives an output-handling instruction ('show the QR, do not decode it') that no structured field conveys.

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

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

Front-loads what is returned and why, then layers the usage condition, expiry caveat, edge case, and display instruction. Every sentence carries distinct, actionable information 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?

With no output schema, the description still tells the agent what comes back (base64/data payload, or a connected-state notice) and how to handle it. For a single optional-parameter read tool, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the instance_id field already documents the ZAPZAP_INSTANCE_ID fallback and the list_instances prerequisite. The description adds nothing about the parameter, so the schema does all the work — baseline 3.

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

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

States a specific verb and resource ('Returns the QR code ... for an instance') plus the concrete user-facing outcome (scan in WhatsApp > Linked devices). It doesn't name a sibling tool explicitly, so differentiation from connect_instance/get_instance_status is implied rather than stated.

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

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

'Use when the instance is disconnected' and 'call again if it expired' give clear when-to-use and retry conditions, and the already-connected case is pre-empted. No explicit exclusion pointing at a sibling alternative such as connect_instance, which keeps it below a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so 'Read-only.' is largely redundant. The genuinely additive content is the note that this MCP server cannot receive webhooks itself, which explains why the URL is exposed for inspection – but nothing is said about behavior when no webhook is configured.

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

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

Three tight sentences with the return value front-loaded and the conceptual explanation following. The trailing 'Read-only.' adds little given the annotations, but the rest earns its place.

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

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

With no output schema, the description carries the return value and does so ('the webhook URL'). Only the edge case of an unconfigured webhook (null vs error) is unaddressed, which is a minor gap for a single-parameter read.

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

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

Schema coverage is 100% and the instance_id description already covers the optional-when-ZAPZAP_INSTANCE_ID-is-set fallback. The phrase 'for the instance' in the description corroborates but does not extend 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 ('Returns the webhook URL currently configured for the instance'), which cleanly separates it from set_webhook and test_webhook siblings. It stops short of explicitly naming those alternatives, but the get/set contrast is inferable.

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

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

The description explains context (webhooks carry incoming messages, delivery status and poll votes) but never says when to call this versus test_webhook or get_webhook_deliveries. Usage is implied by the tool name rather than stated.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so 'Read-only' in the description is redundant. The valuable addition is the enumerated response fields (delivered or not, HTTP status, latency, attempt), which stands in for the missing output schema. It does not disclose the recency window or ordering, which matters for a tool named 'recent'.

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

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

Two sentences, front-loaded with the purpose and the returned fields, then the use case. No filler or restatement of the title.

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

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

With no output schema, the inline field list is what makes this definition callable with confidence, and the debug use case is stated. Remaining gaps are the recency window/retention and result ordering, minor for a small two-param read tool.

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

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

Schema description coverage is 100% and both parameters (limit with default/max, instance_id with env-var fallback) are fully documented in the schema. The description adds nothing about them, so the baseline 3 applies.

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

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

States a specific verb and resource ('Lists recent webhook deliveries') and enumerates the returned fields (event, delivery status, HTTP status, latency, attempt). It is clearly distinct from configuration siblings like get_webhook/set_webhook, though it never names test_webhook, which is the closest functional alternative.

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

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

'Use to debug why your server is not receiving events' gives a concrete triggering scenario, which is more than most definitions offer. It stops short of routing the agent between this tool and test_webhook (inspect real deliveries vs. trigger a synthetic one), so the alternative-selection guidance is incomplete.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine value beyond that by disclosing the return shape (JID format ending in @g.us plus name), which is not in any structured field since there's no output schema. 'Read-only' simply restates the annotation and earns no credit.

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, zero waste, with the core behavior and return shape front-loaded before the usage hint. Nothing could be cut without losing information.

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

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

For a zero-required-parameter read tool with full annotation coverage, the description is essentially sufficient: it says what comes back and why you'd call it. It stops short of noting result volume or whether group listings are paginated, but no pagination parameter exists, so the gap is minor.

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 lone parameter instance_id is fully documented in the schema, including the ZAPZAP_INSTANCE_ID fallback and the list_instances prerequisite. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Lists the WhatsApp groups the instance belongs to') and immediately specifies the return payload (JID ending in @g.us, plus name). This clearly distinguishes it from the singular get_group_info and from create_group/manage_group_participants 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?

Explicitly says when to reach for it: 'Use to find a group JID to send to or manage.' That routes the agent to the right workflow, though it doesn't name an alternative (e.g., get_group_info) or state when-not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered; the description reinforces it with 'Read-only' and adds the prerequisite role in the tool graph. It stops short of mentioning pagination or ordering behavior for large accounts, which is the only 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?

Three short sentences, front-loaded with what it is, then the ordering constraint, then the safety note. No repetition of schema or annotation content beyond a one-word reinforcement.

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 and no output schema, the description carries the load well by enumerating returned fields and stating the call-ordering requirement. Only pagination/volume behavior for accounts with many instances is unaddressed.

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 the baseline is 4. The description usefully documents what the result rows contain (id, name, phone, status), which matters since no output schema exists.

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 (lists WhatsApp instances) plus the scope (all instances in the account) and the fields returned (id, name, phone, status). It is immediately distinguishable from siblings like get_instance_status, which targets one instance.

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 'Call this first to discover the instance_id that every other tool needs', which is a concrete ordering rule rather than vague advice. An agent knows both when to call it and why, relative to the many instance-scoped siblings.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is known. The description adds real value beyond that: the admin authorization requirement, the irreversibility of remove, and the side effect that add notifies the affected people — none of which the annotations convey.

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

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

Two tight sentences: capability and actions first, then preconditions and per-action caveats. Every clause (admin requirement, undo warning, notification warning) carries operational weight with no filler.

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

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

For a destructive, non-idempotent mutation tool with no output schema, the description covers authorization, side effects, and reversibility. It stops short of noting partial-failure behavior for batches of up to 50 participants or what the response contains, which an agent composing a large removal would want.

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 75% and the schema documents group_jid, instance_id, and participants well, but the action enum has no per-value descriptions in the schema. The description supplies that missing semantic layer by spelling out promote/demote/approve/reject meanings, which is exactly the compensation needed.

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

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

Opens with a specific verb+resource ('Changes group membership') and enumerates all six supported actions, including the parenthetical 'promote (to admin)' that clarifies an ambiguous enum value. It is clearly distinguishable from siblings like create_group, get_group_info, and list_groups, which read rather than mutate membership.

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

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

Gives a hard precondition ('The instance must be a group admin') and per-action guidance on when to be cautious with add and remove. It does not explicitly route to an alternative tool (e.g. use create_group for new groups), so it falls 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 this is a mutation (readOnlyHint=false), idempotent, and non-destructive. The description adds meaningful behavioral context beyond the annotations by explaining the unread counter reset and the externally visible effect that the contact may see blue ticks.

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 with no waste: the primary effect is front-loaded, followed by the user-visible consequence and the usage caution. Every sentence adds distinct information.

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

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

For a two-parameter mutation with full schema coverage and annotations that cover safety and idempotency, the description supplies the remaining important context: what changes, what the contact may observe, and when it should be invoked. No output schema is needed to explain return values here.

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

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

Schema description coverage is 100%, and the schema already documents both the chat id number and optional instance_id. The description adds no parameter-specific syntax or constraints, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: marking unread messages of a chat as read and resetting its unread counter. It is clear enough that an agent can distinguish this action from messaging or chat-listing siblings without opening the schema.

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

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

The description gives an explicit usage condition: only after the user has actually handled the conversation. It does not name alternative tools or spell out when not to use it beyond that caution, so it falls short of full when/when-not/alternatives 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?

Beyond the annotations, the description discloses that the reaction is visible to the other person and that an empty emoji removes it. These are useful behavioral facts not captured by the annotation hints, though it could say more about failure modes for invalid message IDs.

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

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

Three tight sentences, front-loaded with the core action, followed by the remove behavior and the visibility warning. Every sentence adds something useful.

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

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

For a four-parameter mutation tool with annotations covering idempotence and non-destructiveness, the description covers the key behavioral points. It does not explain return values, but no output schema exists, so a small gap remains regarding what the reaction response contains or what happens on an invalid message ID.

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 description mostly repeats facts already documented in the schema, such as the OWNER:MSGID format and the empty-emoji removal behavior. With the schema doing the heavy lifting, this is a baseline 3.

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

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

The description states a specific verb and resource: 'Adds an emoji reaction to an existing message.' It is clearly distinct from the sibling send/edit/delete tools by naming the reaction operation, though it does not explicitly contrast itself with those siblings.

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

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

It gives a clear when-to-use rule ('only react when the user asked') and explains the removal behavior ('Pass an empty emoji to remove the reaction'). It does not explicitly point to alternative tools, but the guidance is sufficient for correct invocation.

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, openWorld=true and idempotent=false, but the description adds far more: the non-official WhatsApp Web/QR channel, the ban/restriction risk from unsolicited or repetitive messages, that sends cannot be reliably un-sent, and that a timeout must be reconciled against chat history before retrying. That is exactly the operational context the 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?

Purpose and the 3-button limit are front-loaded, then safety constraints follow in a logical order. It is dense with useful rules rather than filler, though the risk/ban paragraph and the button-type enumeration together make it long enough that the core 'what it does' line gets diluted.

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

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

For a destructive, open-world mutation with 7 params and no output schema, the definition covers safety, opt-in, instance selection (via schema) and retry semantics thoroughly. The one real gap is that it never says what comes back (e.g. a message id usable with edit_message, delete_message or react_to_message), which an agent needs to continue a workflow.

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 earns above that by explaining which nested fields pair with which button type (reply = text+id, link = text+url, call = text+phone, copy = text+copy code) and by adding the cross-parameter rule that button kinds should not be mixed. The "up to 3" restates maxItems, but the type-to-field mapping is genuine 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?

States a specific verb and resource ("Sends a text message with up to 3 buttons") and immediately enumerates the four button kinds, which cleanly separates it from send_text, send_media and send_poll. An agent can pick the right send tool 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 concrete use cases ("menus, confirmations and calls to action"), an explicit constraint ("keep one kind per message"), an opt-in precondition, and a do-not-retry-after-timeout rule. It even explains why the constraint exists (the "open on your phone" notice), so the guidance is actionable rather than advisory.

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 WhatsApp Web/QR (unofficial) channel, the ban/restriction risk, and that a sent message cannot be reliably un-sent, with a retry-after-timeout warning. The annotations already flag destructiveHint=true and non-idempotency, and the description reinforces rather than contradicts them; it could still say more about failure responses, but the safety surface is well covered.

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

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

Purpose is front-loaded in the first sentence, then safety constraints follow in a logical order. The ban-risk sentences are long but carry real decision value; a slight trim of the repeated 'do not send unsolicited messages' framing would tighten it further.

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

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

For a 7-parameter, non-idempotent, destructive send tool with no output schema, the description covers the critical risks: opt-in, channel legitimacy, irreversibility, and retry behavior. It does not describe what a successful or failed send returns, but with no output schema and rich parameter docs the omission is minor.

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 71%, so most parameters (number, digitando, instance_id) are already documented in the schema. The description adds no coordinate format, name/address fallback behavior, or guidance on when digitando should be disabled, so it does not meaningfully extend parameter meaning beyond the schema baseline.

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

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

States a specific verb and resource ('Sends a map location pin') and adds the concrete effect ('opens in Google/Apple Maps'). The resource is unambiguous against siblings like send_text, send_media, and send_poll, so an agent can select it 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 explicit when-to-use ('share an address or meeting point'), explicit when-not-to-use ('Never send bulk or unrequested messages'), a prerequisite (recipient must have opted in), and a confirmation rule when in doubt. Nothing about selection is left to inference.

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

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

Annotations already flag destructive/non-idempotent, but the description adds real operational context beyond them: sends cannot be reliably un-sent, do not retry after a timeout without checking chat history, WhatsApp Web/QR ban risk, and opt-in requirements. This is exactly the safety information an agent needs before calling a high-risk mutation.

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

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

Front-loaded with what the tool does and the URL requirement, then types, then usage and risk warnings. Every sentence carries weight, though the ban-risk paragraph is somewhat long and partly restates the destructive annotation hint.

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

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

For a 7-parameter, destructive, open-world send tool with no output schema, the description covers preconditions, recipient confirmation, retry behavior, and channel risks. It does not say what a successful send returns (message id, status), which would help an agent verify the outcome.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful meaning the schema does not: ptt is a 'voice message bubble', ptv is a 'round video note', document requires doc_name, and caption applies only to image/video. The 'myaudio' enum value goes unexplained, which keeps it from 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 ('Sends a media file to a WhatsApp number or group') and enumerates every media type, so the agent can immediately distinguish it from send_text, send_buttons, send_poll, or send_location.

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

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

Provides a clear use trigger ('Use when the user wants to deliver a file, picture or voice note') plus explicit when-not constraints (no bulk, no unsolicited messages, opt-in required, confirm recipient when in doubt). It stops short of naming sibling tools like send_text as the alternative for plain text, so it is strong but not fully exhaustive.

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 flag the tool as destructive, open-world, and non-idempotent, and the description adds important context beyond that: vote results arrive via webhook, unsolicited messages risk bans, and sends should not be retried blindly after timeouts. This is exactly the kind of behavioral disclosure needed for a risky send operation.

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

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

The description is front-loaded with purpose and vote-delivery behavior, then moves into usage constraints and safety warnings. It is somewhat dense with warnings, but each sentence carries relevant operational meaning for a destructive WhatsApp send 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?

There is no output schema, but the description explicitly explains that votes arrive later via the webhook and not in this response. Combined with the schema and annotations, it gives the agent enough context to invoke the tool correctly and avoid common failure modes.

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 six parameters. The description adds useful single-choice versus multiple-choice meaning for selectable_count, but does not add much beyond the schema for the other parameters.

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

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

The description states a specific verb and resource: it sends a native WhatsApp poll. It also distinguishes the tool's behavior by noting that votes arrive later through the webhook rather than in the send response.

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

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

It gives clear usage context for quick surveys and choices, and explicitly warns against bulk or unsolicited messages. It does not explicitly compare itself to sibling tools like send_buttons, but the when-to-use and when-not-to-use guidance is otherwise strong.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it discloses the unofficial WhatsApp Web/QR channel, the ban/restriction risk, that a sent message cannot be reliably un-sent, and that retrying after a timeout without checking chat history is dangerous. That is exactly the context annotations cannot carry.

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

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

Purpose and use cases are front-loaded, and every sentence carries weight — the safety block is long but justified for a destructive, non-idempotent send with real ban consequences. It could be tightened slightly (the opt-in line and the ban-risk line overlap), but nothing 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?

Return behavior is stated ("Returns the message id and status") even though no output schema exists, and the mutation risks, opt-in requirement, and retry policy are all covered. For a 5-param destructive send tool, an agent has everything needed to call it safely.

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 number, text, reply_id, digitando, and instance_id are all already documented with formats and defaults. The description only restates reply_id ("Supports replying to a message via reply_id") and alludes to instance selection, adding no format or edge-case detail beyond the schema. Baseline 3 applies.

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

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

Opens with a specific verb and resource ("Sends a plain text message to one WhatsApp number or group") and scopes it to the chosen instance, which cleanly separates it from siblings like send_media, send_buttons, send_poll, and send_location. An agent can pick this over those alternatives 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?

Explicitly names the use cases ("replies, notifications and one-to-one conversations") and the exclusion of bulk/unrequested messaging, plus an operational guardrail ("confirm text and recipient with the user first if there is any doubt") and a retry rule after timeouts. This is when-to-use, when-not-to-use, and prerequisite guidance in one place.

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 earns its place by saying exactly what is destroyed — any previous webhook — and by prescribing user confirmation before the overwrite. It also discloses the delivery mechanism and the public-HTTPS requirement, which annotations do not convey.

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

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

Three tight sentences: what it does, what it overwrites plus the prerequisite, then the follow-up call. The destructive consequence is front-loaded right after the effect statement, and 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?

No output schema exists, but the agent does not need one: the description covers the write behavior, the overwrite risk, the confirmation step, and the verification path via test_webhook. Nothing required to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by enumerating the kinds of events the `events` parameter accepts, which the schema only calls 'comma-separated event names'. It still does not mention `exclude_own_messages` or the instance_id fallback, so it is an enrichment rather than full coverage.

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

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

States a specific verb (sets/replaces) and resource (instance webhook) and explains the concrete effect: ZapZap POSTs events to the given public HTTPS URL. It also names the event families (incoming messages, status, connection changes), so an agent can distinguish it immediately from get_webhook and test_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?

Explicit sequencing guidance: call get_webhook first, confirm with the user, then follow with test_webhook. That covers when to use it, the required prerequisite, and the correct next step — no inference left.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that the call performs an outbound test delivery and reports back HTTP status and latency, which is meaningful context beyond the flags. It does not describe timeout/failure behavior or whether the test event is marked as such on the receiver.

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 behavior and return value front-loaded and the usage hint trailing. Nothing to cut.

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 only two optional parameters, full schema coverage, and no output schema, the description covers what the agent needs to call it and even summarizes the return payload. Only the failure/timeout semantics are left implicit.

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

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

Schema coverage is 100% and both parameter descriptions already explain the `url` override and the `instance_id` fallback to ZAPZAP_INSTANCE_ID. The description's 'or to `url` if given' merely restates the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('sends a test event to the configured webhook') plus the return payload (HTTP status and latency), which separates it cleanly from set_webhook, get_webhook, and get_webhook_deliveries.

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 trigger ('right after set_webhook to validate the receiving server') and the alternative target ('or to `url` if given'), so the agent knows the ordering relative to the sibling. No explicit when-not guidance, but the context is unambiguous.

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