wazap-mcp

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

Annotations declare readOnlyHint=true and idempotentHint=false, and the description explains the non-obvious reason: 'The mark moves first', so a repeat call is not idempotent and a swallowed answer requires since: "previous". That is real side-effect disclosure the annotations cannot convey.

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

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

Every clause carries information and the scope comes first, but the telegraphic fragments ('The mark moves first', 'more.cursor: the rest', 'a lost answer is since: "previous"') force the reader to reconstruct the grammar, which costs clarity for very little length saved.

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

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

With an output schema present, return values need not be explained, and the description covers the remaining gaps: breadth across accounts, the token budget, the mark/cursor/repeat interaction. Only the 'waiting' 14-day exception ('whatever the window') is stated so tersely that its interaction with 'hours' stays murky.

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

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

Schema coverage is already 83%, so the baseline is 3, and the description still adds meaning: 'hours ... never moves the mark', 'include' makes the mark stay, 'more.cursor: the rest', 'since: "previous" repeats that catch-up'. These are behaviors of the parameters, not restatements of their types.

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

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

The description opens with 'What the user missed, all accounts' and enumerates the sections returned (waiting, mentions, calls, people, groups, stories), so the resource and scope are clear. It never names a verb, but the digest nature distinguishes it well enough from search/read_messages 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?

'account_id narrows it to one account; get_status names them' gives a concrete routing rule to a sibling. However there is no statement of when to prefer this over read_messages or search, and the 'lost answer is since: "previous"' hint is recovery guidance rather than use-case guidance.

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

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

Beyond the annotations, the description discloses key behavioral traits: it sends only the approved draft text to the approved recipient, sends once per draft, and must not be retried unasked after an unknown outcome. This adds meaningful safety and side-effect context for a high-stakes mutation tool.

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

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

The description is short, front-loaded with the main send action, and every sentence carries operational value. The terse error-handling clauses are efficient rather than wasteful.

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 high-stakes send operation, it covers approval requirements, staleness, idempotency, and unknown-outcome recovery well. It does not describe successful return behavior or explain account_id, leaving a small completeness gap given there is 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?

The schema documents draft_id but leaves account_id undocumented, and the description does not explain account_id either. It reinforces draft uniqueness and approved-recipient semantics but only partially compensates for the 50% schema coverage gap.

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

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

The description uses a specific verb and resource ('Send a draft') and clarifies scope with 'this text, this recipient' and 'the only call that sends, once per draft.' It distinguishes the action from draft creation and from other sending-like siblings.

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

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

It explicitly states when to send, what to do when the user's yes is about something else, what to do for expired/missing/stale drafts, and how to handle SEND_OUTCOME_UNKNOWN. These are concrete when/when-not and recovery instructions.

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 destructiveHint/idempotentHint annotations, the description discloses the 2-day retraction window, the permission rule (own message or group admin), the limited blast radius of the local-delete mode, and the requirement to confirm with the user. These are exactly the facts an agent needs before performing an irreversible action.

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

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

The critical safety instruction (confirm first) and the primary parameter are front-loaded, and no sentence is filler. The second half is a dense run-on clause chain, but every clause carries distinct information about scope and permissions.

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

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

For a destructive, open-world mutation with an output schema, the description covers confirmation, permission scope, time limits, and deletion breadth. Only the account_id parameter and multi-device/account selection semantics are left implicit.

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

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

Schema coverage is 0%, so the description must carry the parameter burden; it does so thoroughly for for_everyeen (both boolean values, their effects, and their eligibility constraints). message_id and account_id remain semantically unexplained beyond their names, which is a small residual gap.

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

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

The description opens with a specific verb and resource ("Delete a message") and immediately distinguishes the two deletion scopes via for_everyone. It is clearly separable from siblings like edit_message or send_message, though it does not explicitly name or contrast any sibling.

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

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

It gives a concrete operational precondition ("confirm with the user first") and explains which mode applies when: for_everyone:true only within 2 days and only for one's own message or as a group admin; for_everyone:false for any message on the linked account's devices. Missing only an explicit comparison to alternative tools (e.g. edit_message) when a message should be changed rather than removed.

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=true, so the description's job is lighter; it still adds the genuinely non-obvious 15-minute window and the ownership constraint. It doesn't say what happens on a rejected/timeout edit or whether the original text is recoverable, which would be the remaining useful detail for a destructive mutation.

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

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

Two short sentences, zero filler, with the ownership scope and the time constraint front-loaded before the fallback advice.

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

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

Output schema and annotations carry much of the load, and the time/ownership constraints are the key behavioral facts. However, for a destructive, open-world mutation with completely undocumented parameters, an agent is left guessing about account_id semantics and the failure modes of an expired or foreign message.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It conveys only that a message and its replacement text are involved, leaving account_id (optional, presumably the linked account selector) and the format/constraints of message_id undocumented anywhere.

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

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

States a precise verb+resource ('Replace the text of a message') and narrows scope to messages 'the linked account sent', which cleanly separates it from send_message, delete_message, and react_to_message in the sibling 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 an explicit eligibility window ('15 minutes after sending') and a fallback action ('send a correction instead'). It stops short of naming the sibling to use for the fallback, so the routing is implied rather than explicit.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses the success shape (contact.chat_id plus number, note, tags, details, and context when writing) and the ambiguity/not_found policy. Gaps remain: 'see fix' is unexplained and it doesn't clarify account scoping behavior. Output schema covers the return payload, so this is solidly above baseline.

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

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

It is short and front-loads the core resolution act, but the compression goes too far: sentence fragments and dangling references ('see fix') cost parseability. Space is saved at the expense of clarity rather than through it.

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

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

For a 7-parameter, output-schema-backed lookup with strong annotations, the description covers resolution inputs, failure policy, write-session context, and the tag-listing mode. What's missing is a clear account_id/multi-account explanation and any note on limits, so it is good but not fully self-contained.

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

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

Schema coverage is 71%, so most parameters are already documented. The description reinforces tag listing ('tag: its people') and hints at qualifier disambiguation ('tells two apart' is in schema, not description), but it adds little on kind, limit, account_id, or include_context beyond what the schema states. Baseline 3 is appropriate.

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

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

The description states a specific job: resolve whatever the user said (name, nickname, relationship, filed detail, group, number, id) into a contact before drafting. It distinguishes itself from plain listing by framing this as 'who the user means', but the phrasing is telegraphic and it never names the obvious sibling (list_contacts) it replaces.

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 real usage context — call it 'before drafting', and on 'ambiguous or not_found: ask the user; never guess' — which tells the agent what to do when resolution fails. The 'Several accounts: see fix' branch points somewhere useful but the referent ('fix') is opaque and not a listed sibling, weakening 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/openWorld, and the description adds useful context beyond them: a 500-participant cap and the fact that the invite link is only returned for an admin (an auth-conditional detail). It does not discuss pagination or failure modes, but the added constraints are valuable.

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

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

It fits the essential information into one dense sentence with no wasted words, and the sequencing cue lands at the end. It reads as a return-value list rather than a front-loaded purpose statement, but nothing is superfluous.

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

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

With an output schema present, the return enumeration is technically redundant but helpful, and annotations cover the safety profile. The only real gap is the unexplained account_id, but otherwise an agent has enough 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?

At 50% schema coverage, only group_id is documented ('<id>@g.us') while account_id is undocumented in both schema and description. The description adds no parameter meaning to compensate, leaving account_id's role ambiguous from the definition alone.

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 enumerates exactly what the tool returns (name, description, owner, participants, settings, community, invite link), making the retrieval purpose clear. It also implies a read-only scope distinct from manage_group. It never quite states a leading verb, but an agent knows what it gets back.

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

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

It gives an explicit sequencing rule: 'Call it before manage_group,' which tells the agent when this precedes a mutation. It does not name alternatives or when-not conditions, but the primary usage context is clear.

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

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

Beyond the annotations (readOnlyHint/not destructive, openWorld), the description adds genuinely useful behavior: transcripts are billed by an API provider, save_to writes a file to the local machine, and a MEDIA_UNAVAILABLE outcome means the media is gone. These cost and failure-mode disclosures are exactly what annotations cannot convey, though the save_to disk-write side effect on a 'read-only' tool could have been called out more explicitly.

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

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

It is short, but the elliptical fragments ('a photo attached as an image; any file saved at path on the machine running wazap; a copy kept on arrival answers first') are dense and hard to parse on first read, so compactness comes at the cost of clarity.

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

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

An output schema exists so return values need not be spelled out, and the description covers media variants and the MEDIA_UNAVAILABLE case. However, for a tool that takes an account_id and writes files via save_to, the absence of any note on account scoping or where files land by default leaves real gaps.

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

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

Schema coverage is 50%: save_to and language are documented in the schema, and the description reinforces save_to's effect ('with save_to its file'), while message_id and account_id receive no explanation anywhere. With half the parameters undocumented, the description only partially compensates.

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

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

The phrase 'What a message's media holds' plus the enumeration (transcript, image, file) makes clear it fetches a message's attachments, but there is no verb-led statement of the action and no differentiation from the sibling get_message, which an agent could easily confuse it with.

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

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

No explicit when-to-use or when-not-to-use guidance is given, and nothing says to prefer this over get_message or search. The only routing-like hint, 'a copy kept on arrival answers first,' concerns caching order, not tool selection, so usage must be inferred.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds one genuinely useful behavioral fact: without account_id the id is looked up across every account. The rest is a return-content inventory (quotes, reactions, poll votes, media, read receipts) that an existing output schema already carries.

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 dense sentence front-loads the core promise ('One message in full') and then enumerates contents efficiently. The only waste is the return-content inventory, which duplicates what the output schema already declares.

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

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

With an output schema present, return values need little prose, and the annotations cover the safety profile; the only real gap an agent would care about is the lack of routing guidance versus read_messages or search. The account_id fallback note fills the other notable hole.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does explain account_id's optionality and its cross-account fallback behavior. message_id is left to the name and its minLength constraint, so the compensation is only partial.

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 title and the opening 'One message in full' state the specific resource and scope, and 'one message' implicitly separates it from bulk readers like read_messages. The description text itself, though, never says the verb plainly and never names a sibling to distinguish against, leaving the differentiation to the title.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative among siblings such as read_messages or search. That this is the single-message, full-fidelity fetch is only implied by 'One message in full'.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds some useful context about what is inspected (sync, history freshness, webhook delivery, versions) and that accounts are listed with a default. It says nothing about authentication requirements, rate limiting, or failure behavior when the account is unreachable.

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

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

It is short and the most useful content (the return-field inventory) comes first, but the structure is telegraphic: a colon list inside a sentence fragment with a trailing ellipsis, followed by a non-sequitur about accounts. Tightening into two clean sentences would cost nothing and read much better.

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

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

There is no output schema, so the enumeration of returned data (status, sync, history freshness, webhook delivery, versions, accounts) carries real weight and is the strongest part. What is missing is the meaning of the enumerated status values and of account_id, which an agent needs to act on the result rather than just fetch it.

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

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

Schema coverage is 50%: include_picture is documented in the schema (including the expiring link), but account_id has no description anywhere. The phrase "accounts lists every account, with default" hints at default-account behavior but never states what account_id defaults to or how it selects an account, so the description only partially compensates for the gap.

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

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

The description makes clear this is a health/diagnostic read of the account: connection status, sync progress, history freshness, webhook delivery, versions, and the account list with the default marked. It is distinguishable from siblings like list_chats or link_account, though the verb is implied rather than stated ("Whether the account works") and the parenthetical with an ellipsis is loose.

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 trigger conditions: "Call it on NOT_CONNECTED, NOT_LINKED or SYNC_IN_PROGRESS." That is more than most definitions offer. However, those state names are never defined or sourced, and no alternative is named for the NOT_LINKED case (link_account is an obvious sibling that is not mentioned).

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 readOnly/idempotent/non-destructive/closed-world, and the description adds the meaningful behavioral point that the call has zero effect on the WhatsApp account itself. It also signals the content categories (ids, workflows, error codes), which is useful for judging whether to call it first, though it doesn't specify the response shape or size.

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

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

One dense sentence that front-loads the topics covered and ends with the strongest routing cue ('read it once, before the other tools'). No filler and every clause carries information.

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

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

For a single-optional-parameter documentation tool with no output schema, the description supplies everything needed: what the guide contains, the account scoping rule, the recommended call order, and confirmation of no side effects.

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

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

Schema coverage is 0% — account_id is an unexplained bare string — and the description compensates by explaining that account_id matters when several accounts are in play. It does not clarify when the parameter can be omitted despite being optional, which keeps it short of a 5.

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

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

A specific resource is named — a guide covering ids, account_id semantics for multi-account setups, workflows, message shape, and error codes — and 'it never touches WhatsApp' immediately distinguishes it from every action sibling. An agent can tell this is documentation retrieval, not an API call, 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?

'Read it once, before the other tools' gives explicit ordering guidance relative to the 22 sibling tools, and the exclusion ('never touches WhatsApp') tells the agent not to expect any live data or side effects. Both when-to-use and what-it-is-not are stated.

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

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

Annotations only declare the safety profile (not read-only, non-idempotent, open-world); the description adds what the agent actually needs: the tool returns a pairing code that must be shown to the user, the exact WhatsApp menu path the user follows, and the required polling cadence until the connection succeeds. That is substantial context beyond 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?

Three sentences, front-loaded with the trigger conditions, then the user-facing procedure, then the polling requirement. No filler; each sentence carries information the agent needs to act.

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 usefully explains that a code is returned and how to use it, plus the completion check via get_status. The only gap is the undocumented account_id parameter, which is minor for the primary linking flow.

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

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

Schema description coverage is only 50% (phone has an example, account_id has nothing), and the description never mentions either parameter. It neither clarifies the phone format required nor explains when account_id should be supplied, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource (pair the app with the user's WhatsApp) and ties it to a concrete precondition surfaced by the sibling get_status. An agent can distinguish this from status-checking or messaging 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?

Explicitly names the four get_status values that should trigger the call (not_linked, logged_out, session_corrupt, auth_failure) and specifies the follow-up loop (poll every 10 s until connected). It also gives the human-facing procedure to hand to the user, leaving little to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description only needed to add context beyond that. It does: result ordering, the set of surfaced fields, and the presence of archived/pinned/muted/left flags. It says nothing about page size behavior or what happens when the account has no chats, so it stops short of a 5.

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

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

Two tight sentences, front-loaded with what comes back and ordering, ending with the actionable purpose. The field enumeration is somewhat redundant given an output schema exists, but it earns its place by letting an agent judge suitability at a glance.

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

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

Return values needn't be explained since an output schema exists, and the description covers ordering and flags. Gaps remain around pagination expectations (limit/cursor are only sketched in the schema), the required account_id, and how this differs from search or list_contacts — for a 6-parameter tool that's the minimum viable level.

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 sits at 67% and the description mentions no parameters at all — tag, filter, cursor, and include_pictures are documented only in the schema, while limit and account_id are undocumented in both places. With the majority of parameters covered by structured fields, the baseline of 3 is right, but the description adds no semantic lift.

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

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

States the specific resource (chats/conversations), the ordering (most recently active first), and the fields returned, plus the concrete downstream purpose (find a chat_id). It does not distinguish itself from siblings like search or find_contact, which is the only thing keeping it from a 5.

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

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

"Use it to find a chat_id" gives one concrete use case, which implies this is the discovery/listing entry point. But there are no exclusions or comparisons to alternatives such as search or list_contacts, so the agent must infer when this beats a search.

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

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

Annotations already declare it a safe, idempotent, open-world read, yet the description still adds real context: results arrive a page at a time, contacts with direct messages excluded from output are omitted, and 'address_book_synced false' means the book has not finished syncing. It adds value beyond the annotations without 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?

Front-loaded with the resource and the returned fields, then the exclusions, then the sync caveat — a logical order with no filler. The telegraphic fragments are dense but each clause carries information.

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

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

With no output schema, the description responsibly enumerates the returned fields (name, E.164 phone, chat_id, contact_id, last DM timestamp/direction). The main residual gap is ordering and page-size behavior, which the schema only partly covers.

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 only 50% — 'order' and 'cursor' are documented inline, but 'limit' and 'account_id' are bare. The description gestures at both gaps ('on one account' implies account scoping, 'a page at a time' implies cursor/limit) but gives no default, maximum, or cursor-lifetime detail, so it only partially compensates.

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 resource (the phone's address book, scoped to one account) and states it is paginated. It is clearly a listing operation, distinguishable from find_contact or list_chats by its roster-of-contacts framing, though it never names a sibling explicitly.

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

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

Usage is only implied: the reader infers this is for enumerating contacts and that find_contact is the lookup alternative. There is no explicit when-to-use/when-not statement, and the '#private people left out' note scopes the output rather than the call decision.

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

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

Annotations already declare destructiveHint=true and non-idempotent, and the description adds genuinely new operational facts: a 15-minute expiry, a single attempt per confirmation, and that optional options must be dropped on the confirming call. It does not say what 'clear' versus 'delete' actually removes, which is the one behavioral detail an agent would still want.

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 with the approval flow and expiry front-loaded and no filler. The telegraphic action list reads as a fragment, but nothing in it 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 16-action, destructive, no-output-schema tool, the description covers the approval mechanics but leaves the action taxonomy under-specified (undo variants and mark_unread unlisted, clear vs. delete undefined) and never states that preview returns a confirmation_id. Adequate to call correctly, but an agent could still mis-select an action.

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

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

With 71% schema description coverage, the schema already documents chat_id, message_id, pin_hours, mute_hours and confirmation_id. The description adds the sequencing rule (confirmation call carries only chat_id/action, no options), which is real value, but it never ties message_id to pin_message/star_message or explains which optional parameters pair with which of the 16 enum actions.

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 enumerates the concrete chat operations it fronts (archive, pin, mute, pin_message, star_message, clear, delete, block) and signals a preview-then-confirm shape, so an agent can tell it apart from siblings like manage_group or delete_message. It is slightly incomplete — the un* variants (unarchive, unpin, unblock) and mark_unread are never named, and the mutated resource ('chat') is only implied by the title.

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 two-phase flow is spelled out: first call previews, then 'repeat chat_id/action with confirmation_id', and 'mark_read runs directly' carves out the exception that skips approval. It lacks any guidance on when to prefer this over siblings such as manage_group or delete_message, so the routing context is only partially covered.

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

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

Annotations already flag mutation, destructiveness, open-world behavior, and non-idempotence. The description adds important context beyond them: admin authorization is usually required, and every change is visible to all members, with a consent workflow. It does not distinguish which of the many actions are especially destructive or irreversible.

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

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

The description is two tight sentences, front-loaded with the three usage modes and followed by the key admin and group-wide side-effect constraints. Every sentence carries useful selection or invocation 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 complex 21-action tool with an output schema and rich annotations, the description covers the operations, admin prerequisite, join preview/confirm flow, and group-wide side effects. It reasonably relies on the schema for per-action parameter mapping, though it could say more about which actions require particular parameters.

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

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

Schema description coverage is 80%, so the input schema already documents most parameters. The description maps action categories and mentions the invite/preview/confirm workflow, but adds little format or syntax detail beyond what the schema provides.

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

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

The description opens with specific verbs and resources: create a group, join from an invite, and administer members, name, description, photo, invite link, join requests, settings, and leave. This clearly separates it from read-oriented siblings like get_group_info and message-oriented siblings.

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

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

It gives concrete usage conditions: join requires a preview then confirm: true, most actions need admin, and group-wide changes require telling users and waiting for yes. It does not name sibling alternatives or say when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare this is a non-read-only, non-destructive, idempotent, open-world operation. The description adds useful behavior beyond that: only one emoji is allowed, and an empty string removes the existing reaction.

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 a single front-loaded sentence with no wasted words. Both the main action and the removal behavior are stated efficiently.

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

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

The tool is simple, has an output schema, and has annotations covering safety and idempotency. The description covers the core behavior sufficiently, though account_id and message_id semantics are left implicit.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains the emoji parameter well, including empty-string removal semantics, but does not explain message_id or account_id beyond their names in the schema.

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

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

The description states a specific verb and resource: reacting to a WhatsApp message. It also distinguishes the add-reaction and remove-reaction cases, so an agent can tell it apart from siblings like send_message, edit_message, or delete_message.

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

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

The description clearly explains the two usage modes: pass one emoji to react, or pass an empty string to remove the reaction. It does not explicitly name alternatives, but the context is clear enough for this narrow operation.

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/openWorld, and the description adds real behavior the annotations don't: history gaps trigger a phone fetch (latency/implication), long texts are truncated unless full_text, and status items are ephemeral (max a day) and appear nowhere else. It does not cover error modes or rate limits, so not a full 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?

Dense and front-loaded, with the main retrieval model in the first clause and the status special case after. The prose is slightly idiosyncratic ("wazap asks the phone") but every sentence carries information, so nothing is wasteful.

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

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

Given an output schema exists and annotations cover the safety profile, the description covers the non-obvious essentials: pagination, truncation, and the stories mode. The main gap is account_id (multi-account selection), which is undocumented in both the schema and the description.

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

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

With 75% schema coverage the baseline is 3, and the description genuinely adds value: it explains the before-based pagination model, the truncation default that full_text overrides, and that "status" is a special chat_id value. `limit`, `types` and `account_id` are left to the schema (account_id is undescribed in both places).

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

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

Opens with a specific verb and resource plus scope: "Read one chat, oldest to newest." It also carves out the special "status" mode for stories, which an agent could not infer from the name. Together these let an agent tell it apart from search, get_message, list_chats and wait_for_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?

Clear context for the two main modes: fetch the latest messages, or page backwards using `before` once you have the oldest message_id. It also flags that stories require chat_id "status" and are time-bounded. It stops short of explicitly naming when to prefer search, catch_up or wait_for_messages 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 declare non-read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower, and the description still adds genuinely new context: storage is local and never written to WhatsApp, and the privacy flags alter how the record is exposed in later reads. The explanation of #private ('keeps their words out of what you did not ask about them by name') is confusing enough to blunt the value, but the disclosure is substantive.

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 constraint (local, never on WhatsApp) is front-loaded, and there is little outright filler. But the single run-on sentence stacks four distinct payload types and two hashtag modifiers into one breath, making it harder to parse than it needs to be.

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

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

An output schema exists, so return values need no explanation, and the annotations cover the safety profile. Still, for an 8-parameter mutation tool with nested objects, the description leaves gaps: precedence when note/fields/add_tags/remove_tags are combined, behavior on a chat_id array (only 'tags and fields only' is hinted), and the relationship to the 'learn' sibling.

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 63%, so the schema carries most of the burden, and the description does add meaning for 'fields' by tying it to what find_contact matches, plus the deletion semantics for note. It says nothing about account_id, remove_tags, remove_fields, or the array form of chat_id beyond the schema's own note, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource ('Keep what the user says about someone, locally') and enumerates what can be stored: note, tags, matched details, and the handled flag. It also implicitly distinguishes itself from send_message by saying 'never on WhatsApp'. The phrasing is compressed and jargon-heavy, but an agent can identify the operation.

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

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

It gives conditional guidance for two cases ('handled: true for an ask dealt with elsewhere', '#no-catchup keeps them out of catch_up'), which is real when-to-use signal. However, it never explains how this differs from the sibling tool 'learn', nor does it state prerequisites such as a linked account or what happens on conflicting writes. Usage is implied rather than fully 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), the description discloses where state lives (kept locally), how it is delivered (posted to the user's webhook when due), and a crucial side-effect exclusion ('Nothing goes to WhatsApp'). It does not say whether cancel is recoverable or what happens to already-fired reminders, so it is strong but not exhaustive.

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

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

The core framing (what it is, where it lives, how it fires) is front-loaded in the first clause, and there is no filler. The mid-sentence parentheticals and semicolon-joined fragments make it slightly telegraphic, but every clause carries information an agent needs.

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

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

For an 11-parameter, three-action tool with an output schema and annotations in place, the description covers the action surface, the timing model and the delivery mechanism sufficiently to call it correctly. Remaining gaps (account_id scoping, pagination via limit, cancel irreversibility) are low-risk and largely covered by the schema.

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

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

Schema coverage is 73%, so some compensation is expected, and the description does add meaning: it maps action values to the parameters they consume (create: chat_id, note, after_hours or due_at) and gives a human-readable gloss of the 'no_reply' condition that goes beyond the schema's terse wording. It leaves account_id, limit, include_closed and reminder_id provenance to the schema.

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

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

The description names the resource (the user's reminders about a chat) and the three supported actions (create, list, cancel) with the key create parameters spelled out. It also implicitly distinguishes itself from messaging siblings by stating reminders are kept locally and 'Nothing goes to WhatsApp'. It stops short of naming a specific sibling tool it supersedes, so not a 5.

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

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

It clarifies the two scheduling modes (after_hours vs due_at) and explains when the 'no_reply' condition fires, with a concrete natural-language example. However, it never states when an agent should pick this tool over a nearby alternative such as scheduled_messages, nor does it state prerequisites for cancel (a reminder_id from create or list). Usage context is implied rather than prescribed.

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

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

The annotations already indicate this is not read-only because cancellation is possible, and the description adds useful behavior: listing order, cancellation before send, and a user-notification requirement for missed/failed messages. It does not contradict the annotations, though it leaves permission and failure behavior for cancellation unstated.

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 compact and front-loaded: it presents the list/cancel choice first, then the scheduling alternative, then the notification requirement. Every sentence adds operational value.

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

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

For a two-action tool with an output schema, this is largely complete: it covers what list returns, how cancel is targeted, and how scheduling relates to sibling tools. The main gap is that limit and account_id are not discussed.

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

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

Schema description coverage is only 40%, so the description should compensate more. It clarifies action modes, schedule_id for cancellation, and include_closed via the week’s sent/missed/failed/cancelled items, but it does not explain limit or account_id.

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

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

The description states specific verbs and resource: list or cancel scheduled WhatsApp messages. It distinguishes itself from scheduling siblings by directing users to send_message with send_at followed by confirm_send.

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 explains both modes explicitly: use list to see scheduled messages and cancel with schedule_id before sending. It also names the alternative workflow for creating a scheduled message and instructs the agent to tell the user about missed or failed messages.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds real behavioral signal beyond that: results include nearby source contexts, come with 'corrections', and carry an 'assessment' that flags ambiguity — though it never says what these look like or how large results are.

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

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

It is short and contains no filler, but the telegraphic fragments ('Check corrections; assessment flags ambiguity') and the trailing agent instruction 'Cite the supporting message' make it read as shorthand notes rather than front-loaded prose. Compact but choppy and harder to parse than necessary.

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

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

With an output schema present, return values need no explanation, and annotations carry the safety profile. However, for a 12-parameter search tool the description leaves the time filters, cursor paging via 'before', and account scoping entirely to the schema, so it is only adequately complete.

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

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

Schema coverage is 75% with 12 parameters, so the baseline is 3. The description does add meaning for 'match' ('words: substrings', exact codes/quoted literals) and rules out guessed tag/from filters, but it says nothing about limit, since/until, chat_id, account_id, full_text, or the 'before' cursor.

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

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

The verb 'Find' plus 'by meaning and words' establishes this as a hybrid semantic/lexical message search, which is distinct from read_messages or list_chats. The resource (messages) is only implicit via the title, so it is clear but not fully self-contained.

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 the question and known context, never guessed filters' gives a query-construction rule, and the auto/words split hints at mode choice, but there is no explicit when-to-use-this-vs-siblings guidance (e.g. versus get_message or read_messages). Usage is implied rather than stated.

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

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

Adds substantial context beyond the annotations: no message leaves the system, the call returns draft_id plus a preview covering recipient, number and exact text, and the preview must be shown before confirm_send. It does not cover rate limits or per-media-type side effects, so it stops short of 5, but the highest-risk behavior (accidental send) is fully disclosed.

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

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

Two dense sentences, front-loaded with the non-sending guarantee before the workflow. Every clause carries instruction the agent needs — the trigger condition, the return payload, and the confirmation gate — with no restatement of the title or schema.

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

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

For a 16-parameter drafting tool with no output schema, the description supplies the missing return-value summary (draft_id and preview) and the confirmation protocol, which is the critical gap. It is slightly thin on the scheduled-send and mention paths, though those are covered by schema descriptions.

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

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

Schema coverage is 75% and the schema already documents per-parameter meaning including the empty-text convention for forwards, so the baseline of 3 applies. The description only names the two required inputs in passing and adds nothing about send_at scheduling, time_zone, mention_ids or account_id.

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

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

Opens with a specific verb and enumerated resource types ("Drafts text, media, polls, locations, forwards") and immediately bounds scope with "sends nothing." That clause alone separates it from the sibling confirm_send and edit_message without opening either schema.

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

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

Gives an explicit trigger ("Call it as soon as you have recipient and text") and an explicit routing rule to the alternative ("confirm_send only on a yes to this text and recipient"). It even resolves an ambiguous case — a send in the same request counts as the yes — 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 already cover readOnly, idempotent, open-world and non-destructive, so the safety profile is done. The description adds genuinely non-obvious behavior: the call blocks for up to timeout_seconds, returns a cursor whose reuse prevents gaps between calls, and addressed_to_me narrows wake-ups to DMs, mentions and replies. It omits what is returned when the timeout elapses with no messages, which is the main 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-loaded with the core action and its timing constraint, then the cursor contract, then the filter. Three dense clauses with no repetition of annotations. 'For agents that stay on the line' is a slightly decorative closer, but it frames the intended usage rather than wasting space.

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

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

Return values are covered by the existing output schema, and the crucial cross-call cursor contract is spelled out, which is what an agent needs to loop correctly. Missing only the empty-timeout outcome and any guidance on chat_id/account_id scoping; for a 5-param, zero-required tool that is close to complete.

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

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

Schema coverage is only 40%, so the description must compensate, and it does for three of five params: cursor provenance, addressed_to_me's exact semantics, and timeout_seconds as an upper bound. chat_id and account_id are left to the schema (chat_id has a description there, account_id has none), which is a minor shortfall rather than a blocker.

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 ('wait for messages'), plus scoping ('from other people, up to timeout_seconds') and a distinguishing long-poll mechanism (cursor returned and passed back). It does not name the close siblings read_messages or catch_up, so an agent must infer the difference, but the 'wait/block' semantics separate it from the fetch 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?

'For agents that stay on the line' and 'pass it to the next call so nothing... is missed' imply the streaming/long-poll use case, but there is no explicit when-to-use-vs-alternatives guidance — nothing says to prefer read_messages for a one-shot fetch or catch_up for backlog. Usage is inferable rather than stated.

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