wazap-mcp

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

Annotations already declare not read-only, not idempotent, open-world, and non-destructive. The description goes beyond them by disclosing the draft-consumption side effect and the draft expiry/error path, which explains why the operation is non-idempotent and what a caller must do on failure. It stops short of describing the success response (e.g., resulting message id/status), which is the one 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?

Front-loads the core action and the 'only call that reaches WhatsApp' distinction, then adds the consumption and expiry facts. Four short sentences, each carrying distinct 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?

For a two-parameter mutation tool with no output schema, the description covers purpose, routing, side effects, and the error-recovery path, which is enough for correct invocation. It could optionally state what the caller receives on success, but nothing essential is missing.

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

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

Schema coverage is 100%, so both draft_id and account_id are already documented in the schema, including the account_id resolution fallback logic. The description repeats that draft_id originates from a send_* tool but adds no format, constraint, or usage 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?

States a specific verb (send/confirm) and resource (draft from send_* tools), and explicitly bounds the scope with 'the only call that reaches WhatsApp'. An agent can immediately tell it apart from send_message, send_media, and the other drafting 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 routes the agent: drafts come from send_message/send_media/send_poll/send_location/forward_message, and this is the single call that actually delivers. It also gives a recovery rule for the missing/expired draft case (draft again and re-show the preview). 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 readOnly=false, idempotent=false, destructive=false, and openWorld=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the per-participant status vocabulary (ok, invite_needed, failed) tells the agent to expect partial success rather than all-or-nothing.

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

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

Two sentences with no filler; the core action and required inputs come first, and the return-status detail is efficiently packed into the second 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 3-parameter mutation tool with no output schema, the description covers the action, required inputs, ownership effect, and return statuses. It stops short of explaining failure handling (e.g., what happens if every participant fails) or limits, but the essentials 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 the schema already documents name, account_id, and participant_ids with constraints and defaults. The description only restates 'name and participants' and adds no format or resolution 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 and resource ('Create a group'), names the required inputs ('given name and participants'), and adds the ownership outcome ('the linked account becomes the owner'), which cleanly separates it from read-oriented siblings like get_group_info and manage_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?

The creation context is implied by the verb, but there is no guidance on when to use this versus manage_group, nor any prerequisites (e.g., the account must be linked) or exclusions. Adequate but leaves the agent to infer routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds non-obvious behavior the annotations cannot convey: the retraction is visible to everyone in the chat, it is restricted to the sender's own messages, and it has a 2-day eligibility window. That is exactly the extra context needed before a 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?

Two sentences, zero filler, and the DESTRUCTIVE warning is front-loaded ahead of the constraints. Every clause carries information the agent needs.

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

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

For a destructive mutation with no output schema, the description covers the safety profile, the confirmation requirement, the visibility consequence, and the two eligibility constraints — the full set of facts an agent needs to call it responsibly. Annotations and schema fill the remaining structured gaps.

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

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

Schema description coverage is 100%, so message_id, account_id, and for_everyone are already fully documented in the schema (including the default-resolution behavior of account_id). The description adds only the sender-restriction fact, which mildly relates to message_id semantics but does not go beyond the schema's own 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 resource ('Retract a message') and immediately distinguishes the operation from siblings like edit_message or send_message by naming the retraction semantics. An agent can identify the correct 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 explicit operational conditions: only messages the linked account sent, only within 2 days of sending, and a required user confirmation before invoking. These are the precise conditions under which the tool succeeds or must be avoided.

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 the safety profile is covered. The description adds real value beyond that: it discloses a filesystem side effect (writes to disk on the host), the inline-return behavior for images ≤1 MB, and the specific error code MEDIA_UNAVAILABLE for expired media.

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 is downloaded and where, followed by the inline-image nuance and the failure mode. No filler, no repetition of the name or 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?

There is no output schema, yet the description covers the practical return behavior (file on disk, inline image for small files) and the key failure mode. A brief note on the returned path/format and whether existing files are overwritten would make it fully complete.

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

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

Schema description coverage is 100%, so message_id, save_to, and account_id are already fully documented in the schema, including the default save directory. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (download) and resource (photo/video/audio/document attached to a message) plus the destination (save to disk on the wazap host). An agent can distinguish this from read_messages, get_message, or transcribe_audio without opening a schema.

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

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

Usage is implied by the purpose (you call this when you need the actual file for a message). There is no explicit when-to-use vs alternatives guidance, e.g. it never says to use this instead of transcribe_audio for audio or that the message must have has_media=true. The MEDIA_UNAVAILABLE note is a failure condition, not 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 the mutation safety profile (readOnly=false, destructive=false, idempotent=false), so the description's key added value is the 15-minute time-limit constraint, which is a real behavioral trait the agent cannot infer from annotations. It stops short of describing edit side effects or the result payload, but the time window is the critical 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 sentences, zero filler, with the core action stated first and the constraint immediately after. Every clause earns its place.

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

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

For a simple three-parameter mutation with full schema coverage and annotations carrying the safety profile, the description supplies the one non-obvious constraint (the edit window). No output schema exists, so return values need not be explained; only minor gaps like side-effect detail remain.

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 message_id, text, and account_id are already documented inline. The description confirms the target is a message 'the linked account sent' but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb ('Replace the text') and resource ('a message the linked account sent'), which cleanly separates it from siblings like send_message and delete_message. An agent can identify the operation without opening the schema.

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

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

Gives an explicit precondition (only within 15 minutes of sending) and the alternative action when that window has passed ('send a correction instead'). Both when-to-use and when-not-to-use are 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent, openWorld). The description adds genuinely new behavioral context: nothing is transmitted until confirmed, the recipient sees the message marked as forwarded, and a preview is surfaced. That goes beyond what the structured fields 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 short sentences with zero filler; the critical constraint ('Does not send') and the next-step routing are front-loaded and 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?

For a 3-parameter drafting tool with no output schema, the description covers the key concerns: no transmission occurs, the preview should be shown, and the confirmation path is named. It stops short of describing what the draft object returns, but nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so message_id, to_chat_id and account_id are already fully documented inline. The description mentions 'existing message' and 'another chat' but adds no format, resolution fallback, or constraint detail 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?

Specific verb ('Draft a forward') plus a specific resource ('an existing message to another chat'), with immediate disambiguation from sending tools via 'Does not send.' An agent can distinguish it from send_message/confirm_send without opening a schema.

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

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

The description clearly scopes the operation ('Does not send') and routes the agent to the follow-up tool and its trigger ('after the user says yes, call confirm_send'). It doesn't explicitly compare against alternatives like send_message for non-forward cases, but the workflow condition is stated plainly.

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, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds value by listing the returned fields, which helps the agent know what data is available, but it says nothing about error behavior, account requirements, or rate limits.

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

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

A single front-loaded sentence with no waste. The list of returned fields is efficiently packed and directly 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?

With no output schema, the description does the important work of enumerating returned fields, which compensates well. It omits parameter constraints and error cases, but for a simple read tool whose annotations and schema cover those areas, it is nearly complete.

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

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

Schema description coverage is 100%, so the schema fully documents contact_id and account_id. The description does not mention either parameter by name or add any usage detail beyond what the schema provides, 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 the specific resource (one contact) and scope (full details), enumerating the exact fields returned. The singular 'one contact' distinguishes it from plural-list siblings like search_contacts and list_chats without 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?

There is no explicit when-to-use guidance, no mention of alternatives, and no prerequisites. The phrase 'Full details for one contact' implies a retrieval use case but offers no routing or exclusion rules.

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, so the bar is lower, and the description adds real traits beyond them: the participant list is capped at 500 while participant_count is the true total, and the invite link is only returned when the linked account is an admin. These conditional/truncation behaviors are genuinely useful and not derivable from the annotations.

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

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

Two tight sentences: the return contents are front-loaded, followed by the conditional invite-link rule and a one-line usage note. Zero wasted text.

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

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

With no output schema, the description carries the return-value burden and does so well by enumerating fields and their conditions; the read-only safety profile is covered by annotations. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% (both group_id and account_id are documented in the schema, including the account resolution fallback), so the description adds no syntax or format detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description names a specific verb+resource ('Details of a group') and enumerates the exact fields returned (name, description, owner, creation date, admin-only posting, participant list), which an agent can use to distinguish it from manage_group or create_group 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?

It explicitly routes usage: 'Call this before manage_group: most group actions need admin rights,' giving the sequencing condition that selects this tool. It does not state explicit when-not-to-use cases, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds value beyond that by disclosing the return content shape (quoted message, reactions, media metadata), which matters because there is no output schema. It does not cover error behavior for an unknown message_id, keeping it below 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, zero filler, and the payload content is front-loaded before the routing advice. Every clause earns its place.

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

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

For a 2-param read tool with no output schema, the description supplies the missing return-content detail (quoted message, reactions, media metadata) plus entry-point guidance. Failure modes (unknown or inaccessible message_id) are not mentioned, so it is not fully complete.

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

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

Schema description coverage is 100%, so both account_id (fallback resolution rules) and message_id (format example) are already fully documented in the schema. The description adds no parameter meaning beyond that, which is the baseline 3 case when the schema does the heavy lifting.

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

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

States a specific verb and resource ('The complete message behind a message_id') and immediately enumerates what 'complete' means: quoted message, reactions, media metadata. An agent can distinguish it from read_messages and search_messages 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 says to use it 'after search_messages or read_messages when you need the context around a single message', naming the sibling tools that precede it. It stops short of stating when *not* to use it (e.g. bulk retrieval should use read_messages), so it is clear context without exclusions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description adds genuine behavioral context beyond them: WhatsApp system notices are excluded from bodies AND counts by default, with include_system to reveal them. It does not disclose output structure or pagination/size limits, keeping it below 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?

Front-loaded with purpose and the replacement relationship; three sentences with little waste. The em-dash aside about left-out notices is slightly dense but earns its place by explaining the count semantics.

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, all-optional-parameter tool with 100% schema coverage and no output schema, the description covers scope, default exclusion behavior, and sibling routing adequately. Return-shape detail is not required given the schema and absence of an output contract.

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 all 7 optional parameters in detail. The description restates only the include_system default behavior, adding marginal value over what the structured fields provide; 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+resource and scope: 'everything that happened recently, grouped by chat' and self-labels as 'the catch-up tool.' Crucially it distinguishes itself from siblings by declaring it replaces 'list_chats plus a read_messages per chat,' so an agent can route 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?

Provides clear usage context ('catch-up') and names the alternatives it consolidates (list_chats + read_messages). It also flags the include_system parameter for system notices. It stops short of explicit when-not guidance, e.g., when to prefer search_messages or get_unanswered instead.

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

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

Annotations already mark this as a safe, idempotent read, and the description adds substantial behavior beyond them: the meaning of each status value, the 'linking' intermediate state with a pairing code, the semantics of contacts_named: 0, and the default-account fallback. This is rich operational context an agent cannot get 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-loads the core purpose and keeps the trigger conditions in the second paragraph. It is dense and long, but nearly every clause carries distinct information (status values, pairing code, contacts_named), so little is wasted.

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

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

With no output schema, the description carries the full burden of describing returns, and it does so thoroughly: status values and their meanings, sync state, linked account, last-message time, versions, data directory, and the accounts array. Nothing an agent needs to interpret the response 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 parameter is fully documented in the schema (100% coverage), so baseline is 3. The description goes further by explaining the consequence of omitting account_id — top-level fields reflect the default account while `accounts` lists every live one — which adds meaning beyond the schema's wording.

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 ('Check the session: connection status') and enumerates the exact fields returned, so an agent knows precisely what this returns. It is clearly distinguished from siblings like link_account and list_accounts by its diagnostic scope.

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

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

Explicitly names the trigger conditions ('whenever another tool reports NOT_CONNECTED, NOT_LINKED or SYNC_IN_PROGRESS') and a second use case ('to confirm which account you are about to send from'). It also explains what the not_linked state implies and the remediation command, which is exactly the routing guidance an agent needs.

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

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

Annotations already cover read-only/idempotent/open-world safety, and the description adds real substance on top: a 24-hour retention rule ('nothing older is held'), newest-first ordering, and how previews are produced (WhatsApp's preview when available, otherwise downloaded once and shrunk locally). It stops short of covering auth or per-call cost implications.

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

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

Four sentences, front-loaded with scope and ordering before mechanics; nearly every clause carries information. Slight redundancy in 'WhatsApp keeps a story for a day and so does wazap' costs a point but not much.

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 shape (author, text/caption, time, optional preview images) and the retention/ordering rules, which is everything an agent needs to invoke and interpret this read-only tool correctly.

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

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

Schema coverage is 100%, which sets a baseline of 3, but the description adds meaning beyond the schema: previews arrive as 'small images', the retention ceiling explains why hours caps at 24, and it links message_id semantics to download_media. account_id receives no additional explanation, keeping 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: the stories (status updates) the linked account has received in the last N hours, newest first, each with author, text/caption and time. It explicitly distinguishes itself from siblings by noting stories never appear in chats, catch-ups or waits, so an agent can route correctly without opening a schema.

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

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

Gives a clear when-not for sibling tools ('Stories never appear in chats, catch-ups or waits; this is the only place they show') and points to download_media for retrieving a story's media via message_id. It lacks explicit guidance on choosing hours or when previews are worth requesting, but the routing context is 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 cover safety (read-only, idempotent, non-destructive), and the description goes well beyond them: abandonment semantics for max_age_hours, group-chat inclusion logic, business-account auto-reply weighting, and output ordering. This is rich behavioral context an agent cannot infer from the structured fields.

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

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

Front-loads the core definition, then layers exclusions, group logic, output shape, and routing. It is dense but a few parenthetical example tokens and the caveat sentences make it longer than strictly necessary; still, nearly every sentence carries selection-relevant 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?

No output schema exists, and the description still tells the agent what each entry contains (the quoted ask, count of messages since the user's last reply, waiting duration) plus ordering (people first, then oldest wait). Nothing material for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description still adds interpretive value: max_age_hours is framed as 'abandoned, not waiting,' and min_age_hours is illustrated with 48 hours for forgotten asks, giving an agent a reason to choose thresholds rather than just valid ranges.

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

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

States a specific resource ('chats where the last word is theirs and it asks for something') with the exact inclusion heuristic, and explicitly distinguishes itself from the sibling get_recent_messages. An agent can tell what this returns and why it exists 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?

Explicit routing: 'use get_recent_messages for what happened, and this for who is still waiting.' It also gives exclusion conditions (ended in 'ok, thanks', older than max_age_hours, group chats without @-mention or reply) and caveats for business accounts, so the agent knows when not to expect a row.

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/closed-world, so the safety bar is low. The description adds value by specifying exactly what content is returned (guide, id formats, workflows, message shape, error remediation) and reinforcing that it 'never touches WhatsApp,' useful given no output schema. Minor tension: it says 'Takes no arguments' while the schema exposes an optional account_id.

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

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

Three tight sentences with the imperative 'Read this FIRST' front-loaded, then the return contents, then the no-side-effect guarantee. No wasted words for a documentation tool.

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

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

For a zero-required-param meta tool with no output schema, the description fully covers purpose, timing, return contents, and side-effect profile. Nothing an agent needs before calling it 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 account_id's meaning is already fully documented in the schema, which sets the baseline at 3. The description's claim that it 'takes no arguments' adds no detail and is slightly at odds with the optional account_id, so it does not earn above 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: returns the guide covering tools, id formats, recommended workflows, message shape, and error codes. The title and description together make clear this is the meta/documentation entry point, cleanly distinguished from all 32 sibling action tools.

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

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

Explicitly instructs 'Read this FIRST, before any other WhatsApp tool,' which is an unambiguous when-to-use directive. For a bootstrap/documentation tool there is no meaningful alternative to exclude, so the guidance is complete.

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 discloses rich operational behavior (returns a code, expires, requires polling, account prerequisite, ACCOUNT_NOT_FOUND), but it directly contradicts the annotations: readOnlyHint=true is false for a pairing/write action, and idempotentHint=true conflicts with 'call this again for a fresh one.' This is an annotation contradiction.

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 trigger conditions, then gives the user-facing link steps, polling behavior, expiry handling, prerequisites, and error case. Despite its length, every sentence contributes to correct invocation.

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

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

For a multi-step linking tool with no output schema, the description is complete enough: it explains what is returned (a code), how to present it, how to verify connection via get_status, how long to wait, and what to do if the code expires.

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 phone format and account_id. The description adds useful semantics beyond the schema: pass account_id when multiple accounts are configured and an unknown id returns ACCOUNT_NOT_FOUND.

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 action and resource: pairing this wazap with the user's WhatsApp account. It clearly distinguishes this from get_status by making get_status the trigger/status-check sibling, not the linking action.

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

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

It gives explicit when-to-use conditions (get_status says not_linked, logged_out, session_corrupt, or auth_failure), explicit when-not-to-use guidance (never when already linked), prerequisites (account must exist), and the alternative action for an expired 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 already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. With no output schema, the description adds real behavioral value by naming the returned fields, including that phones are masked and that write permission is exposed, plus the note that account_id is effectively ignored for listing.

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 resource and field list front-loaded, followed by routing guidance and the argument note. Nothing is wasted, though the clause about account_id being ignored is slightly at odds with the schema's resolution wording and could be sharper.

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-argument read tool with no output schema, the definition covers what is returned, when to call it, and how to chain account_id into other tools. Pagination or account-limit behavior is not mentioned, but for an account registry that is a minor gap.

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

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

Schema description coverage is 100% so the schema already documents account_id (default, work, resolution from chat_id/message_id). The description adds a nuance the schema does not state plainly: that account_id is ignored for this listing call, clarifying that it does not filter results.

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 every configured WhatsApp account') and enumerates the returned fields (id, name, connection status, masked phone, owner, write permission), so an agent knows exactly what the tool produces. No sibling tool overlaps this listing behavior, so differentiation is implicit but clear.

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

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

Gives explicit sequencing guidance: 'Call this first when more than one account is linked, then pass account_id on the other tools.' That is clear context for when to use it, though it offers no exclusions or naming of an alternative listing path (e.g., resolving accounts implicitly elsewhere).

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/destructive=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: result ordering, and the semantics of fields like 'left' (groups you are no longer in) — useful since there is no output schema to document them.

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

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

Two tight sentences, front-loaded with purpose and ordering before the return-shape list. Every clause carries information an agent needs; nothing is padded.

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

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

With no output schema, enumerating the returned fields is the right compensating move, and the ordering plus 'left' semantics round it out. Only minor gaps remain, such as pagination guidance beyond the limit cap — which the schema already bounds.

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 subtle note that filter="all" excludes archived chats, so the schema already carries the parameter meaning. The description adds no param syntax, defaults, or interaction guidance (e.g. how limit interacts with filter), 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 ('List conversations') plus the ordering guarantee ('most recently active first'), and frames the tool's role as a chat_id discovery step. This clearly separates it from siblings like read_messages or search_messages, which consume those ids rather than produce them.

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

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

'Use it to discover the chat_id values the other tools need' gives a concrete condition for choosing this tool over its siblings. It stops short of naming specific alternatives or exclusions (e.g. when to prefer search_contacts for a known name), but the routing intent is unambiguous.

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

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

Annotations declare the write/non-idempotent/non-destructive profile, and the description adds genuine side-effect detail: mark_read sends read receipts and mute defaults to 8 hours. It stops short of stating reversibility or permission requirements, but it goes beyond the annotations meaningfully.

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

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

A single front-loaded sentence that packs the action list and two key defaults without padding. The dense parentheticals cost a little readability but 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 a 4-param mutation tool with full schema coverage and no output schema, the description covers actions, defaults and visible side effects. Auth requirements and whether archived/muted state is reversible are the only real gaps.

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

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

Schema description coverage is 100%, so the parameters are already documented. The only added meaning is that mark_read triggers read receipts; the mute_hours default of 8 merely restates 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 concrete verb+resource ('Change the state of a chat') and enumerates every supported mutation (archive/pin/mute/mark_read and inverses), so the agent immediately knows the scope. It is clearly separable from siblings like manage_group or send_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 list of actions implies when the tool applies, but there is no explicit statement of when to choose this over alternatives (e.g. manage_group for group-level settings) or any prerequisites. Usage must be inferred from the action enum.

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 documenting the per-participant result statuses (ok, invite_needed, failed), the irreversible consequence of leave, and the admin-permission requirement. Annotations already cover the safety profile (destructiveHint, idempotentHint), so this extra operational detail is genuinely additive; only return shape for the non-participant actions is undocumented.

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 one-line purpose followed by a dense action list; every line carries either a parameter requirement or a behavioral warning. No filler 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?

With 5 parameters, no output schema, and mutation semantics, the description supplies the prerequisites, destructive caveat, and partial result semantics an agent needs. Gaps are minor: no description of what get_invite_link returns or how failures for non-participant actions surface.

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 maps actions to their required parameters ('add / remove / promote / demote — need participant_ids', 'set_subject / set_description — need value'), which the schema alone does not express. That action-to-parameter binding is real added 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+resource ('Administer a group') and then enumerates the exact action set (add/remove/promote/demote/leave/set_subject/set_description/get_invite_link/revoke_invite_link), so an agent immediately knows the tool's scope. It does not explicitly distinguish itself from siblings like create_group or get_group_info, though the enum implicitly excludes 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?

Explicitly states the precondition ('Everything except leave requires the linked account to be a group admin') and prescribes a routing step ('call get_group_info first to check'). It also warns that leave is destructive and rejoining needs an invite, giving clear 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?

Adds substantial behavior beyond the annotations: the mark is local-only, nothing is sent or marked read on WhatsApp, and the handled state auto-reverses when the other side next messages. This mirrors and enriches the idempotentHint=true / destructiveHint=false annotations rather than contradicting them.

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

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

Three sentences, front-loaded with the triggering situation before the state effect and the local-only caveat. Dense but each sentence carries distinct information; the WhatsApp reply aside is slightly incidental but still clarifying.

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 safety/idempotency and a fully described schema, the description supplies the remaining behavioral context an agent needs: what is mutated, what is not transmitted to WhatsApp, and how the state reverses on its own.

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 chat_id and account_id are already documented in the schema. The description adds no parameter-level syntax, format, or resolution detail beyond that, which is the expected baseline when the schema does the work.

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

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

States a specific verb (mark handled) on a specific resource (the open ask in a chat) and names the observable effect: the chat leaves get_unanswered. This lets an agent distinguish it from siblings like get_unanswered or manage_chat without opening any schema.

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

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

Gives a clear triggering condition: the user dealt with the ask outside WhatsApp (phone call, meeting, decision). It also contrasts the state transition with get_unanswered's listing behavior, though it does not explicitly name an alternative tool or an exclusion 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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the agent knows this is a non-destructive mutation. The description's one notable behavioral addition, that an empty string removes the reaction, is already duplicated in the schema parameter description. It adds no auth, rate-limit, or return-value context beyond what structured fields supply.

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

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

A single well-formed sentence that front-loads the primary action and includes the removal case with zero padding. Nothing is wasted.

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

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

For a simple 3-parameter mutation with no output schema, the description plus the 100%-covered schema convey everything needed to call it correctly. Only minor gaps remain (no mention of account context or response behavior on success/failure), which are low-stakes 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%, so all three parameters (emoji, account_id, message_id) are fully documented in the schema, including the empty-string removal trick and account resolution fallback. The description adds no syntax or semantic detail beyond that, 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+resource ('add an emoji reaction to a message') and includes the inverse operation (removal), making the tool's scope unambiguous. It does not explicitly name a sibling tool, but the reaction semantics are specific enough to distinguish it from send_message or edit_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?

Usage is implied by the description ('add an emoji reaction' / pass empty string to remove), which effectively tells an agent how to invoke both modes. However, there is no explicit guidance about when to use this versus alternatives like send_message, nor any prerequisites or account resolution notes.

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 readOnly/idempotent/non-destructive, so the bar is lower. The description adds genuine behavioral context beyond them: default ordering, and that paging past the local store makes wazap query the phone and take a few seconds. It omits pagination termination cues (e.g. what an empty result means), so it stops short of 5.

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

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

Two short sentences, front-loaded with the core action, then the paging mechanic. Every clause carries information; nothing is padding or restated from 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?

With no output schema, the description should carry return-shape burden; it states ordering and the default/most-recent behavior, which is the essential part for a read tool. It does not describe what a message record contains, so it is not fully complete for a six-parameter tool with no 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 description coverage is 100%, so the baseline is 3. The description nonetheless adds meaning over the schema's terse 'Return the messages immediately older than this message_id' by framing `before` as the oldest message_id you already have, i.e. the paging cursor. Other parameters (limit, types, include_previews) get no description-level elaboration.

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 (Read), resource (messages), and scope (one chat, oldest to newest), which is more than a tautology of the name/title. It does not explicitly differentiate itself from close siblings like get_recent_messages or search_messages, so the agent must infer the boundary from the ordering/paging phrasing.

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 conditional guidance: 'Without `before` you get the most recent messages' and 'Pass `before` ... to page further back'. That tells the agent when to supply the parameter, but it never names when to prefer a sibling such as search_messages or get_recent_messages, leaving the tool-selection boundary implicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description still adds real behavioral detail: how matching is performed (substring vs digit match) and what the returned identifiers can be used for. It stops short of ordering, cross-account behavior, or limits, which keeps it out of 5 territory.

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 with no filler, front-loading the find operation and using the second sentence to state the return value. Every clause earns its place.

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

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

For a three-parameter, read-only lookup with no output schema, the description covers purpose, matching behavior, and the meaning of the returned id, which is the key piece of output information. Gaps remain around result ordering, whether the search spans accounts, and truncation behavior, but the essentials 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 coverage is 100%, so the baseline is 3, and the description goes beyond it by clarifying how `query` is interpreted — substring on names and digit matching on numbers, which tells the agent that phone formatting does not matter. It adds nothing for `limit` or `account_id`, so it is not a full 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 (Find) and resource (contacts) plus the exact matching semantics (substring on name, digit match on number) and what the output is good for. That is far more precise than a bare 'search contacts'. However, it never names or contrasts with the nearest sibling, get_contact, so an agent must infer the boundary between the two from the names alone.

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

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

Usage is only implied: the note that results are 'usable as chat_id' hints at when you would reach for this tool, but there is no explicit 'use this when you know a name/phone but not the id' statement and no mention of get_contact or sync_contacts as alternatives. Adequate but leaves the agent to infer the routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world. The description adds a genuinely useful non-obvious constraint — the local-sync data boundary — that annotations cannot convey. It does not describe result ordering or pagination behavior.

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

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

Two tight sentences with the core capability front-loaded and the limitation following immediately. Every clause earns its place; no restatement of the name or title.

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

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

For a read-only search tool with a rich, fully documented 7-parameter schema and no output schema, the description covers purpose, scope, and the key data-boundary caveat. It omits anything about result volume defaults/ordering, but those are secondary.

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 seven parameters (from, limit, query, since, until, chat_id, account_id) are already documented in the schema. The description's 'all chats, or one chat' allusion to chat_id adds nothing 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 (case-insensitive text search) and resource (messages), plus scope (all chats or one chat). This distinguishes it from read_messages and get_recent_messages, which retrieve rather than search.

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

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

Gives clear context for use (local search over all chats or one chat) and an explicit boundary — it cannot reach messages never synced to the device. It does not name sibling alternatives (e.g., read_messages for a whole thread), so routing is implied rather than spelled out.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is partially covered. The description adds the non-obvious behavioral fact that this call produces a draft only and never transmits, which is meaningful beyond the annotations. It does not mention auth/account requirements, but the schema's account_id description covers that.

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

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

Three short sentences, front-loaded with the core action, followed by the critical 'does not send' caveat and the required next step. No filler.

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

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

For a mutation tool with no output schema, the description supplies the workflow context an agent needs: it drafts rather than sends, a preview is shown, and confirm_send completes the action. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter (name, address, chat_id, latitude, longitude, account_id). The description only restates that name/address are optional labels, adding little semantics beyond the structured fields. 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 ('Draft') and resource ('a map pin, optionally labelled with a place name and address'), and explicitly says 'Does not send', which separates it from the send-family siblings (send_media, send_message, confirm_send). An agent can identify the 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 operating procedure: show the preview, wait for user confirmation, then call confirm_send. This names the required follow-up sibling and the condition that triggers it, leaving nothing 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 declare mutation and non-destructiveness but say nothing about limits or side effects; the description supplies that the call only drafts, caps at 100 MB, and requires ffmpeg on the host for GIF conversion (.gif converted to mp4, mp4 loops). This is exactly the extra behavioral 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?

Front-loaded with the core action and source options, then the draft/confirm workflow, then limits and format detail. Every sentence carries information, though the GIF/ffmpeg clause is dense enough to be slightly hard to parse on first read.

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

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

With no output schema and 8 parameters, the description covers the drafting-vs-sending distinction, the mutually exclusive inputs, the size ceiling, dependency requirements, and the handoff to confirm_send. 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 per-field descriptions do the bulk of the work (baseline 3). The description still adds non-obvious constraints absent from the schema: exactly one of file_path/url is required, and the as_gif semantics for mp4 vs .gif. That pushes it above 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 (Draft) plus the resource types (image, video, audio, document, GIF) and the source locations (local path or public URL). It is clearly distinguishable from send_message, download_media, and confirm_send, which all deal with adjacent but different actions.

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

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

Explicitly says 'Does not send' and routes the agent to the follow-up tool: 'after the user says yes, call confirm_send.' It also clarifies the alternation between file_path and url. The when-to-use and what-happens-next are both spelled out.

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

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

Adds substantial behavior beyond the annotations: the call does not send, it returns a draft_id and a recipient/text preview, and the draft expires in 15 minutes. The annotations only declare non-readOnly, non-destructive and non-idempotent; the description supplies the stateful draft lifecycle and the required user-confirmation step that drive correct usage.

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 most important fact (it drafts, it does not send), then return values, then the required next step, then the expiry. Every sentence carries load 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?

No output schema exists, but the description compensates by naming the return value (draft_id plus preview) and the mandatory confirm_send step, plus the 15-minute validity window. For a stateful two-step mutation flow, this is sufficient for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents chat_id, text, reply_to, account_id and mention_ids in detail. The description adds no parameter-level syntax or defaults, 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 name 'send_message' implies a send, but the description immediately corrects this with 'Draft a text message. Does not send.' — a specific verb+resource combined with a scope correction that an agent cannot infer from the name alone. It also names the follow-up sibling confirm_send, distinguishing this from the tool that actually sends.

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 workflow guidance: show the preview to the user, and after approval call confirm_send. This tells the agent when to escalate to the sibling. It stops short of stating when to prefer send_media/send_poll/send_location for non-text payloads, 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?

Annotations cover safety flags (destructiveHint=false, openWorldHint=true), but the description adds genuinely non-obvious behavior beyond them: the tool drafts rather than sends, and votes are cast in WhatsApp and cannot be read back by wazap. That limitation is valuable context an agent could not infer. It stops short of describing the returned preview payload or whether drafts expire.

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 core fact ('Draft a poll. Does not send.') and ending on the required next action. The line break is slightly awkward but 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?

With no output schema, the description still conveys that a preview is produced and must be confirmed, which is the key return-value behavior. It leaves the exact preview contents and any draft lifetime unstated, but is otherwise sufficient 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 description coverage is 100%, so chat_id, options, question, account_id, and multi_select are all documented in the schema itself, including the 2-12 option bound and multi-select semantics. The description adds no parameter-level detail beyond that, so the baseline 3 is correct.

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 ('Draft a poll') and immediately disambiguates from the send path by asserting 'Does not send.' An agent can distinguish it from confirm_send and send_message without inspecting 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?

Prescribes the exact workflow: show the preview, wait for the user to say yes, then call confirm_send. This is an explicit when-to-use plus the named alternative, leaving nothing 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?

Beyond the annotations (which only declare it is a non-read, idempotent, non-destructive write), the description adds high-value behavior: the note is stored on this machine only, nothing is sent to WhatsApp, the contact never sees it, and it propagates to five named tools. These are exactly the traits an agent cannot infer from 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 purpose, then effect, then privacy, then removal — a logical order with no filler sentences. The inline quoted examples are slightly informal in formatting but earn their place by demonstrating note format.

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

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

For a 3-parameter tool with full schema coverage and no output schema, the description covers everything an agent needs: local-only scope, cross-tool visibility, privacy, and removal. 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%, so all three parameters are already documented in the schema, including the empty-string removal semantics. The description's examples of note content add mild meaning but do not go beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource (remember/set a note about a person) and immediately differentiates itself by explaining where the note surfaces (list_chats, search_contacts, get_contact, get_recent_messages, get_unanswered). This lets an agent distinguish set_contact_note from sibling read tools 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?

It gives concrete context for use via examples ("the accountant", "always answers late") and states the removal condition for empty notes. There is no explicit when-not or named alternative tool, but no sibling competes for this function, so the guidance is clear without exclusions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, yet the description adds genuinely new context: the picture is 'visible to every contact', the call 'hits WhatsApp immediately', there is 'no draft', plus format and 10 MB size limits. That is real behavioral disclosure beyond the structured hints.

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

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

Front-loaded with the core action, then constraints, then the safety workflow. Every sentence earns its place; no padding.

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 carries return expectations on its own, and it does. Source alternation, format/size limits, visibility, immediacy and the confirmation requirement together make this callable and safe without further reference.

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

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

Schema coverage is 100% so the baseline is 3. The description adds the 'Exactly one of file_path / url' mutual-exclusivity rule, which the schema (additionalProperties:false but no oneOf) does not encode, plus format/size constraints. That is added value 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 (set) and resource (the linked account's own profile picture), with the scope 'own' clarifying this is not editing someone else's picture. An agent can distinguish this from send_media or download_media 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 clear operating context: 'Show the image and wait for a yes first' and 'This call hits WhatsApp immediately; there is no draft.' It also states the source constraint. It stops short of naming an alternative tool for a different profile-photo scenario, but the when-to-use confirmation workflow is well specified.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral facts: a bounded up-to-15-second wait, an explicit assurance that nothing on WhatsApp changes, and the names and interpretation of the return fields (named_before/named_after, with both zero meaning the phone has no saved contacts).

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

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

Four tight sentences, front-loaded with the action and its cost (up to 15 seconds), followed by scope, trigger conditions, and return-value interpretation. 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 compensates by explaining what is returned and how to read it, and it covers trigger conditions, latency, and side-effect scope. An agent has everything needed to call and interpret 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?

Only one optional parameter exists and schema description coverage is 100%, so the schema already documents account_id fully. The description adds nothing about parameters, 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 ('Ask WhatsApp to send the linked phone's address book from scratch') and immediately scopes it ('this only refills wazap's own contact list'), which cleanly separates it from siblings like search_contacts and get_contact that read the existing list.

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 explicit triggering conditions ('when get_status reports contacts_named: 0', or 'when senders in a group read as phone numbers for people you know are saved on the phone') and names the sibling tool to check first, leaving no inference needed about when to reach for this.

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 past the annotations (readOnly/idempotent/destructive=false) by disclosing caching (a repeat call is free), the cost model (local whisper.cpp free and offline vs API provider uploading audio to a third party and billed per minute), a rate limit (10 calls/minute), and precise error semantics for TRANSCRIBE_UNAVAILABLE with the instruction not to retry. This is exactly the extra behavioral context an agent cannot get from 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 paragraphs: what it does and its downstream effect first, then cost/privacy/rate limits, then error handling. Every sentence carries load-bearing information (cache, cost, offline vs upload, rate cap, error fix) 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?

No output schema exists, and the description compensates by showing the transcript's rendered form ('[voice message · 0:42] "what was said"') and its searchability. Combined with cost, caching, rate-limit and error coverage, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so language, account_id and message_id are already documented in the schema (defaults, resolution order, ISO codes, accepted message types). The description adds no parameter-specific syntax or format detail 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 (turn into text) and resource (voice note / audio message), which is a distinct operation from siblings like download_media or read_messages. An agent can immediately tell this is the speech-to-text conversion tool and not a media-download or message-reader.

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

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

Clear context for use (voice/audio messages) and it spells out the downstream effect in read_messages, get_recent_messages, get_message and search_messages, plus explicit when-not guidance: do not retry on TRANSCRIBE_UNAVAILABLE. It stops short of naming a concrete alternative tool or a prerequisite chain, so it is clear context rather than fully explicit when/when-not/alternatives.

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

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

The description adds substantial behavioral context beyond the annotations: it blocks until a message arrives, returns empty on timeout, returns only messages from other people, ignores WhatsApp system notices, supports addressed_to_me filtering, resets cursors from previous runs, and caps timeouts at 55 seconds due to MCP client limits. These are exactly the operational details an agent needs and are not covered by the readOnly/idempotent annotations.

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

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

The core purpose is stated first, followed by usage, filtering behavior, cursor rules, and timeout limits. Every sentence adds a distinct operational detail, and there is no redundant or filler content.

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

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

Given the lack of an output schema, the description explains what is returned (a message or empty) and how cursors work. Annotations cover safety and openness, while the description covers blocking semantics, filtering, cursor reset, and timeout constraints. Nothing essential for correct use appears 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?

Although schema description coverage is 100%, the description adds meaningful semantics beyond the schema: cursor must be passed from the previous call and cannot be honored across runs, addressed_to_me has specific wake conditions, and the timeout cap is explained by MCP client limits. This meaningfully improves correct invocation.

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 blocking behavior: wait until a message arrives, return it, or return empty on timeout. It distinguishes itself from polling-based siblings by explaining it is how an agent stays on the line without polling, though it does not name specific sibling tools like read_messages or get_recent_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?

It gives clear operational guidance: call in a loop, pass the cursor from the previous call, and rely on the timeout. It explains filtering behavior and cursor reset conditions, but does not explicitly name alternative tools or state when not to use this tool versus read_messages.

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