wazap-mcp

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

Discloses critical behavior beyond annotations: at-most-once sending, already_sent responses, session ownership, the need for fresh user approval after reconnecting, and SEND_OUTCOME_UNKNOWN handling. This aligns with openWorldHint=true and idempotentHint=false and adds substantial context.

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 sentence carries operational weight. The description is front-loaded with the purpose, then efficiently covers idempotency, session constraints, failure recovery, and unknown outcomes. No filler or redundant restatement of 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?

Given there is no output schema, the description fully covers what the agent needs to invoke this safely: success semantics, idempotent re-confirmation, session validity, recovery from missing/expired drafts, and handling of SEND_OUTCOME_UNKNOWN. It is complete for a side-effect-heavy tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that draft_id is session-scoped, single-use, and can expire, which directly affects how the agent should treat the parameter. account_id is already well documented 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?

States a specific verb and resource: 'Send a draft created by send_message, send_media, send_poll, send_location or forward_message.' It also distinguishes itself from siblings by declaring it is the only call that reaches WhatsApp, making its role 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?

Provides explicit when-to-use and when-not-to-use guidance: only after drafting, only within the creating session, and never when draft_id is missing/expired without re-drafting and showing a preview. It also names read_messages as the check for SEND_OUTCOME_UNKNOWN, giving a concrete alternative action.

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?

Beyond the destructiveHint annotation, the description discloses the exact consequences of each deletion mode, including whether the change is visible to others, the 2-day time window, and the NOT_OWN_MESSAGE error condition. This gives the agent a thorough understanding of what will actually happen, which is especially important for a destructive operation.

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

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

The description is front-loaded with the key warning "DESTRUCTIVE — confirm with the user first," followed by a well-structured bullet list. Every sentence earns its place, and the two alternatives are presented in a scannable, unambiguous 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 destructive tool with multiple behavioral subtleties, this description covers the essential scenarios: own messages, admin deletions, non-own messages, device-only deletion, and time limits. The optional account_id and source of message_id are covered in the schema, so nothing critical is missing for correct invocation.

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

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

The input schema already documents all parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining the limitations and side effects of for_everyone true versus false in detail. It does not add much for account_id, but the schema description covers that sufficiently.

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 clearly states the tool's function with a specific verb and resource: "Delete a message." It also explains the two deletion modes, making the core purpose unmistakable. However, it does not explicitly differentiate itself from the sibling tool 'recall', which may also perform message deletion.

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

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

The description provides clear context for when to use each for_everyone setting, including time limits, message ownership, and admin capabilities. It also instructs the agent to confirm with the user before proceeding. It does not explicitly list alternative tools for similar operations, so it stops short of full when/when-not guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, and non-destructive flags, but the description adds substantial behavioral detail: the file is pre-decrypted, inline return for small images, detailed result field semantics (filename vs original_filename, caption nullability), id resolution in raw form, account fallback behavior, and the MEDIA_UNAVAILABLE error. This goes well beyond the annotations and fully informs the agent of side effects and edge cases.

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 long but each section delivers unique information: action, result fields, id handling, failure case. It is front-loaded with the primary action and then flows logically into details. No fluff; every sentence adds value. However, the length is near the upper bound of what an agent can parse quickly, so it loses a point for brevity, not for redundancy.

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

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

With no output schema, the description must fully explain the return value, and it does: all result fields, their types, nullability, and relationships. It also covers error conditions (MEDIA_UNAVAILABLE) and resolution nuances across accounts. For a 3-parameter tool with this complexity, the description is comprehensive and leaves no functional 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?

The schema already covers all three parameters with descriptions (100% coverage), giving baseline 3. The description adds meaningful context: it explains the id resolution format for message_id, the behavior of account_id when omitted (walks all linked accounts), and the default for save_to. This enriches parameter understanding beyond the schema, so a 4 is warranted.

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: 'Download the photo/video/audio/document attached to a message and save it to disk.' It immediately distinguishes this from sibling tools like send_media (sending) and transcribe_audio (processing audio). The mention of inline return for small images further clarifies behavior.

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

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

The description clearly implies when to use the tool (when a message has media to download) but does not explicitly contrast it with alternatives or state exclusions. It gives prerequisites implicitly via the message_id requirement ('A message with has_media=true' in schema) and explains behavior when account_id is omitted, which helps the agent decide. However, no explicit 'use this instead of X' guidance exists, so not 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 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, and destructiveHint=false, so the safety profile is covered. The description adds value by detailing the return fields and explaining the name_source enum, which is beyond what annotations provide. It does not mention potential errors or rate limits, but for a read-only fetch that is not critical. It aligns with annotations and enhances understanding of the tool's 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?

The description is two sentences: the first states the purpose and lists fields, the second explains name_source. It is front-loaded with the core purpose and contains no filler. Every sentence earns its place, and the structure is clean and scannable.

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

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

For a simple read-only tool with two parameters and no output schema, the description is quite complete. It enumerates the returned fields and clarifies the ambiguous name_source values, which is essential for correct interpretation. It does not cover error handling or edge cases, but those are not typically required for such a straightforward getter. Overall, it provides enough context for an agent to use the tool effectively.

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

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

Schema description coverage is 100%, so both parameters (account_id and contact_id) are already well-documented. The description does not add new parameter semantics beyond the schema; it merely references the same sources for contact_id. Since the schema handles the heavy lifting, the description meets the baseline of 3 but does not exceed it.

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

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

The description clearly states it retrieves full details for a single contact and lists the specific fields (name, number, about text, profile picture URL, saved/business/blocked status). This distinguishes it from sibling tools like get_message (message details) and get_group_info (group details), and from update_contact_details (which is a write operation). The verb 'get' plus the resource 'contact' is precise and unambiguous.

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

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

The description implicitly indicates usage by mentioning 'one contact' and referencing contact_id sources (search_contacts/list_chats), which tells an agent where to obtain the identifier. However, it does not explicitly state when to prefer this over search_contacts (e.g., when you need a single contact's full profile versus a list) or when not to use it. It gives clear context but no exclusions, so it earns a 4.

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/destructive annotations, the description discloses important behavioral nuances: participant list is capped at 500 while participant_count is the true total, invite links are returned only for admins, and setting fields like info_locked and member_add_mode have specific meanings. This is substantial added context beyond the annotations.

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

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

The description is dense but well-structured, front-loading the core result fields and then adding the conditional invite-link behavior and settings. No sentence is wasted, and the manage_group guidance is placed at the end without bloating the definition.

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 absence of an output schema, the description carries the burden of explaining the return shape, and it does so thoroughly: fields, limits, conditional values, and setting semantics are all covered. The parameter schema is complete, and the usage context is clear, making the tool fully callable by an agent.

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

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

With 100% schema description coverage, the schema already documents both group_id and account_id thoroughly. The description adds only indirect context about 'the linked account' being an admin, which lightly reinforces the account_id parameter's role but does not materially extend the schema.

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

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

The description clearly identifies a retrieval tool: 'Details of a group' followed by a concrete list of returned attributes (name, description, owner, settings, participants). It also differentiates itself from the sibling manage_group by positioning itself as the prerequisite call.

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

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

The description gives an explicit usage directive: 'Call this before manage_group: most group actions need admin rights.' This tells the agent when to use the tool, but it does not mention when not to use it or compare it against alternative info-gathering siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds substantial behavioral detail: delivery status semantics, read-receipt behavior in groups, raw lid id resolution, cross-account fallback, and the exact shape of sender identity fields. This goes far beyond the annotations and gives an agent precise expectations.

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 long but well-structured, with clear paragraphs for purpose, delivery status, id resolution, and sender fields. Each sentence carries substantive information. It is not wasteful, but it is longer than strictly necessary for a 2-parameter tool; however, given the complexity of WhatsApp messaging semantics, the length is justified. The core purpose is front-loaded, so it remains navigable.

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 tool with no output schema, the description fully explains what to expect in the response: message content, quoted message, reactions, poll/event answers, media metadata, delivery status, and sender identity fields. It covers id resolution edge cases and account behavior. Nothing an agent needs to call it correctly and interpret results 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 schema already describes both parameters well (account_id and message_id with examples), so the baseline is 3. The description adds meaningful extra semantics: how message_id can be a raw lid form, how resolution falls back across accounts, and how account_id restricts the lookup. It does not fully cover every edge case, but it enriches the schema meaningfully, earning a 4.

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 clear verb ('get') and resource ('message'), and specifies exactly what it returns: the complete message with quoted replies, reactions, poll/event answers, and media metadata. It explicitly differentiates itself from siblings like search_messages and read_messages by positioning itself as the follow-up for single-message context.

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

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

It gives explicit when-to-use guidance: 'Use it after search_messages or read_messages when you need the context around a single message.' This clearly tells an agent the appropriate trigger and distinguishes it from list-retrieval tools. It also covers account-resolution nuances, leaving no ambiguity about when to pass account_id.

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 annotations, it discloses meaningful behavior: system notices are excluded from bodies and counts by default, include_system re-enables them, results are grouped by chat, and each chat is capped at its newest 2,000 messages. This is substantial behavioral context an agent would not otherwise know.

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 with no filler; the core purpose is front-loaded, and every sentence adds either scope, usage context, or a behavioral limit. It is concise without sacrificing needed detail.

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, all-optional tool with rich schema descriptions and safety annotations, the description supplies the essential high-level semantics: grouping, system-notice handling, and the per-chat message cap. No critical selection or invocation information 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 all seven parameters. The tool description adds little parameter meaning beyond mentioning include_system, which the schema already covers; baseline 3 applies.

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

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

The description identifies a specific verb and resource: retrieving recent WhatsApp conversations grouped by chat, and positions it as 'the catch-up tool.' It distinguishes itself from the composed alternative of list_chats plus read_messages, making its purpose unmistakable.

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 use it: 'This is the catch-up tool: one call instead of list_chats plus a read_messages per chat.' This names the alternative and the efficiency condition, giving an agent clear selection 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 mark this as read-only, idempotent, and non-destructive. The description goes far beyond that by explaining what each status means, what 'stale' indicates, what contacts_named: 0 implies, how webhook delivery counters behave, and what happens while a link is in progress. This is rich behavioral context with no 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 long but every clause carries diagnostic information that the agent needs, especially since there is no output schema. It front-loads the primary purpose and the trigger conditions, then details fields and failure semantics. The length is justified by the breadth of status data covered.

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 must compensate, and it does: it covers all major status categories, linking behavior, default-account handling, webhook delivery fields, and staleness semantics. An agent can correctly interpret the tool's response and decide when to invoke it without missing critical context.

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

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

There is one optional parameter and the schema already covers its meaning at 100%. The description adds value by explaining the default-account behavior when account_id is omitted and that the response then also includes an accounts list. This goes beyond the schema's 'resolve from chat_id or message_id' phrasing.

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

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

The description opens with 'Check the session' and then enumerates exactly what the tool reports: connection status, history sync, linked account, freshness, versions, data directory, contacts_named, and webhook delivery metrics. This clearly distinguishes it from siblings like send_message or get_recent_messages, which perform 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?

The description gives explicit trigger conditions: 'Call this whenever another tool reports NOT_CONNECTED, NOT_LINKED or SYNC_IN_PROGRESS, or to confirm which account you are about to send from.' It also explains account_id omission behavior. It lacks an explicit when-not-to-use or named alternative, but the context is clear and actionable.

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

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

Annotations 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?

The description goes well beyond the annotations by explaining the preview behavior ("Without confirm: true it joins nothing"), the visible side effect ("Every member sees the account join"), and the pending_approval result. This is particularly valuable because idempotentHint: false and readOnlyHint: false leave behavioral details unexplained without extra context.

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 detailed but every sentence earns its place: the invite formats, the confirm condition, the return values, and the visible side effect are all stated without redundancy or filler. The structure is front-loaded with the core mechanics before the confirmation instructions.

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

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

For a 4-parameter two-phase tool with no output schema, the description is complete: it defines the inputs, the preview response fields, the confirmed response (chat_id or pending_approval), and the side effect of joining. An agent has enough context to call the tool correctly and interpret its result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter semantics beyond the schema: it clarifies the exact-one-of requirement for invite/message_id and distinguishes the preview call from the confirm call. This extra guidance justifies a 4.

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 clearly states the action as "Join a group from an invite" and specifies the accepted invite forms (link or code, or invite message_id), which distinguishes it from sibling tools like create_group, get_group_info, and manage_group. The title and description together convey the exact scope of the operation 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?

It gives explicit invocation guidance: exactly one of invite / message_id must be supplied, and the two-phase confirm flow is described step by step (preview without confirm: true, then call again with confirm: true after user consent). It does not explicitly name alternative tools or exclusions, but provides clear context for when this tool should be used.

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

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

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?

The annotations already declare destructiveHint=true and readOnlyHint=false; the description adds critical behavioral context beyond those: which actions are DESTRUCTIVE, that clear/delete affect only the linked account, that mark_read sends read receipts, and that every action hits WhatsApp at once with no draft. This materially improves an agent's ability to call the tool safely. It does not contradict the annotations.

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

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

The description is long, but its bullet-style list is scannable and information-dense. Each line justifies its place by explaining an action, a parameter requirement, a default, or a safety warning. The final warning about immediate execution and the need for confirmation is valuable and appropriately placed. Minor deduction for verbosity, but the complexity of the tool justifies 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 tool with 16 actions, 6 parameters, destructive annotations, and no output schema, the description is substantially complete. It covers what each action does, necessary parameters, defaults, the person-chat restriction for block, and the no-draft/immediate-execution behavior. It does not specify response/return values, but with no output schema defined, that burden is reduced. Some per-action edge cases (e.g., preconditions for unpinning or unstarring) are not covered, which prevents a perfect score.

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 schema coverage at 100%, the baseline is 3. The description goes beyond the schema by tying message_id specifically to pin/star actions and stating it must belong to chat_id, explaining mute_hours default, clarifying pin_hours allowed values and default, and spelling out the semantics of clear vs delete. This adds meaning beyond the structured 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-resource pair ('Change a chat, or a message in it') and enumerates 16 distinct actions. It clearly distinguishes this tool from siblings like send_message, delete_message, and edit_message by covering the full set of chat- and message-management 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?

The description gives clear when-to-use context for each action: which need message_id, that block/unblock only applies to person chats, and that clear/delete are destructive only-for-linked-account operations. It does not explicitly name sibling tools as alternatives, but the exhaustive action list and the destructive/confirm warning make operation selection unambiguous. Minor deduction for not explicitly stating when not to use this tool relative to sibling tools.

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

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

Goes well beyond the annotations by disclosing that leave is destructive and requires a new invite to rejoin, that all changes are immediately visible with no draft, and that set_picture requires explicit confirmation before sending. This adds genuinely useful behavioral context beyond destructiveHint, readOnlyHint, and idempotentHint.

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 long because the tool supports 19 actions, but every sentence earns its place. It is front-loaded with the purpose, then organized as a scannable action list, followed by shared prerequisites and warnings. No filler or repetition.

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

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

For a complex multi-action tool with no output schema, the description covers the critical context: admin requirements, destructive behavior, confirmation protocol, accepted values, and result statuses. An agent has enough information to invoke the correct action, supply the right parameters, and set user expectations.

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

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

Although schema coverage is 100%, the description adds important constraints not in the schema: exactly one of file_path or url for set_picture, image format/size limits, participant_ids for approve/reject must come from list_join_requests, and the status values returned per participant. This materially improves an agent's ability to construct valid calls.

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 verb 'Administer a group' and immediately enumerates the full set of group management actions (membership, subject, picture, join requests, settings). It clearly distinguishes itself from siblings like create_group, join_group, and get_group_info by covering post-creation administration.

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 operational context: call get_group_info first to verify admin status, confirm with the user before making visible changes, and note that leave is destructive. It does not explicitly name alternatives such as manage_chat or create_group, but the action list makes the tool's scope unmistakable.

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 cover readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds genuine behavioral value beyond those: the phone-side fetch on cache exhaustion and its latency ('takes a few seconds'), which an agent needs to anticipate slow calls.

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 paragraphs with zero waste. The core purpose and ordering are front-loaded in the first sentence, followed only by the essential paging/latency behavior. 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?

The description covers ordering, paging mechanics, and latency—the key non-obvious behaviors. Given the schema handles all parameter semantics and annotations handle the safety profile, nothing critical is missing for an agent to call this tool correctly. A return-format description would be a minor enhancement but is not required.

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 all six parameters. The description body adds some practical context on how `before` drives paging, but since the schema already describes each parameter, the description contributes only marginal extra meaning, matching the baseline 3.

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

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

States a specific verb+resource ('Read messages from one chat') with explicit ordering ('oldest to newest'). The paging detail distinguishes it from siblings like get_recent_messages (recent only) and get_message (single message), making the scope unambiguous.

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

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

Provides explicit, actionable paging guidance: 'Without `before` you get the most recent messages. Pass `before` ... to page further back'. This clearly instructs when and how to use the paging parameter, though it does not explicitly name alternatives or state when-not-to-use cases against sibling tools.

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

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

Beyond the annotations (readOnly/openWorld/idempotent/non-destructive), the description discloses many behavioral traits: fused ranking, age weighting (85% a month, never under 70%), per-chat placement caps, near-duplicate handling, similarity floor, keyword fallback with mode marker, index-only limitations, and coverage/freshness reporting. This is far more than the annotations alone 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?

The description is long, but every paragraph earns its place given the tool's complex fusion and fallback behavior. It is front-loaded with the core purpose, then proceeds logically through output fields, parameter semantics, edge cases, and failure modes. There is no filler or tautology.

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 sophisticated search tool with no output schema, the description covers return values, ranking semantics, filtering behavior, index-only limitations, fallback mode, error conditions, and coverage/freshness fields. Combined with 100% schema coverage and strong annotations, nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: query is 'said any way — the meaning is what matches', from supports name resolution to exactly one person, and since/until narrow exactly like search_messages. It does not redundantly re-explain every field, yet enriches the params with behavioral 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?

The description opens with a specific, vivid statement of what the tool does: 'Search by meaning and by words at once over the whole WhatsApp history'. It gives concrete example queries and explicitly contrasts itself with search_messages for exact strings, so an agent can distinguish it from siblings without inspecting schemas.

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

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

It explicitly names when to prefer search_messages ('For an exact string — an id, a phone number, a URL') and when this tool is the right choice (meaning-based or word-plus-meaning search). It also explains fallback behavior when semantic recall is unavailable, and says quote words for 'index only' hits with get_message as the recovery path.

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 indicate destructive and non-readonly behavior. The description adds specific consequences: the chat and history remain, and nothing is sent to the contact. This goes beyond annotations by clarifying what is NOT affected, which is valuable for an agent.

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

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

The description is two sentences with no filler. It front-loads the main action and then adds precise behavioral details. Every sentence earns its place.

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

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

For a simple destructive tool, the description covers the key behavioral outcomes (what is removed, what persists, no notification). It does not mention return values or error cases, but given the schema coverage and annotations, it is adequately complete for an agent to invoke correctly.

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

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

The input schema has 100% parameter description coverage, providing clear meanings for account_id and contact_id. The description adds no additional parameter-level information, so a 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 uses a specific verb ('remove') and resource ('contact'), and explicitly clarifies the scope: only the saved entry and name are removed, while chat history is preserved. This clearly distinguishes it from sibling tools like update_contact_details and save_contact, and from chat deletion 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?

The description clearly states the operation (removing a contact) and provides contextual detail (chat history stays, no notification). However, it does not explicitly mention alternatives or when not to use this tool, though the intent is unambiguous from the context.

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 indicate a non-readonly write operation, and the description adds concrete side effects: name syncs to all linked devices and optionally to the phone's address book. It also clarifies that no other fields are stored, which helps set expectations beyond what annotations convey.

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

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

The description is compact and front-loaded with the core purpose, then adds essential behavioral detail and a sibling distinction. Every sentence carries information without redundancy.

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

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

For a write tool with full schema coverage and no output schema, the description covers the primary use cases, side effects, and scope. It lacks explicit error or prerequisite information, but the tool is straightforward and the provided detail is 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 coverage is 100%, so the baseline is 3. The description adds meaning by explaining that save_on_phone controls phone-book writes and by clarifying that the name field is for the contact name only (with notes going elsewhere). This enriches the parameter semantics beyond the schema.

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

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

The description states a clear verb (save) and resource (WhatsApp contacts), and distinguishes two use cases: creating a new entry or renaming an existing one. It also explicitly routes non-name fields to set_contact_note, which differentiates it from that 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 clearly explains when to use the tool (new contact or rename) and gives an explicit exclusion for notes via set_contact_note. It doesn't enumerate all sibling tools but provides sufficient context to avoid the most common confusion.

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/openWorld/idempotent annotations, the description reveals matching semantics ('substring match on the name, a digit match on the number, or a word from a local tag or detail'), tag-only behavior, and that results are contact_id values usable as chat_id. No contradiction with 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 front-loaded in the first sentence, and the subsequent sentences each add non-obvious behavior (tag-only listing, return format). It is slightly longer than strictly necessary because of the worked example, but the example 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 read-only search tool with 100% schema coverage and no output schema, it explains matching modes, the tag-only case, and return value. The only noticeable gap is that behavior when combining both tag and query is not explicitly clarified.

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 covers all parameters, so baseline is 3. The description adds meaningful semantics for query and tag: substring vs digit vs word matching, tag-only listing, and an example tying 'contabil' to a detail updated by update_contact_details. It does not add much for limit or account_id, but the schema already documents those.

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 'Find contacts by name, phone number, tag or detail' and specifies the matching modes (substring, digit, word). It distinguishes itself from siblings like search_messages and get_contact by targeting contacts and returning contact_id usable as chat_id.

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 clearly describes when to use the tool: any contact lookup by name, number, tag, or detail, and notes the tag-only case for listing all carriers. It does not explicitly name alternatives or exclusions, so it misses the top bar for explicit 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?

Beyond the readOnly/idempotent/open-world annotations, the description discloses scan limits (scan_capped, searched_back_to), coverage semantics, sender-field meanings, and freshness staleness/partiality. This is extensive behavioral transparency with no contradiction against the annotations.

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

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

The description is long but dense; each paragraph covers a distinct aspect (scope, coverage/scans, from resolution, sender fields, freshness). Some repetition of the schema's `from` detail occurs, but given the complexity and lack of an output schema, the length is largely justified.

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 fully explains the meaningful return fields (`coverage`, `sender`, `freshness`) and the operational caveats (cap, sync, unsynced data). An agent has everything it needs to invoke the tool and interpret results correctly.

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

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

The input schema already covers every parameter well (100% coverage), so baseline is 3. The description adds meaningful resolution semantics for `from` (contact names, notify names, pushnames, display names) and clarifies error behavior with candidates, plus coverage-related output context that helps interpret parameter effects.

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

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

The description opens with a specific verb+resource ('Substring search over the messages wazap holds locally') and immediately defines scope (all chats or one chat) and key behavior (case/diacritics ignored). It clearly conveys what the tool does and distinguishes it from siblings like get_recent_messages or search_contacts 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?

It states the intended context (searching locally held WhatsApp messages) and gives actionable guidance for handling scan caps ('narrow it (chat_id, since/until, a longer query)') and explains the limit of unsynced messages. It does not explicitly point to alternative tools, but the usage context is clear enough.

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?

Annotations already signal readOnlyHint=false, openWorldHint=true, idempotentHint=false. The description adds rich behavioral context beyond that: it does not send, it returns a preview, drafts expire after 15 minutes, and mention handling appends missing @<number> tokens. This fully discloses side effects and the exact preview semantics, exceeding what annotations alone 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?

The description is concise yet complete. The first sentence states the core purpose and the non-sending nature; the next explains the flow and draft expiry; the second paragraph details mention syntax. Every sentence adds operational value, with the most critical information front-loaded.

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

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

Given the tool's complexity (5 parameters, no output schema), the description fully covers return values (draft_id, preview), the required user confirmation step, draft timeout, and mention behavior. It provides everything an agent needs to call it correctly, including edge cases like missing mentions, so nothing essential is omitted.

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 adds value by specifying the @<number> syntax for mentions and clarifying chat_id formats (WhatsApp ID vs phone number). It also explains that the preview is the exact outgoing text, which clarifies the text parameter's role. This goes beyond the schema's field-level descriptions, earning a 4.

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 'Draft a text message' – a specific verb and resource – and immediately clarifies 'Does not send,' distinguishing it from sending tools. It explicitly names the sibling confirm_send and describes its own output (draft_id, preview), so an agent can tell it apart from related tools like send_media 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?

It gives explicit when-to-use guidance: show the preview and only after user approval call confirm_send. This routes the agent to the correct sibling. It also explains the draft's 15-minute lifetime, setting expectations for the workflow. No alternative is left ambiguous.

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

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

The annotations only signal that this is not read-only, not idempotent, and not destructive. The description adds key behavioral context: the tool creates a draft without sending, poll votes behave in a specific way, and confirmation via confirm_send is required. It could go further by describing the state of the draft or the exact preview mechanism, but it is substantially transparent.

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 core purpose, and each sentence contributes meaningful guidance. There is no redundancy or filler.

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

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

The workflow is clear, and the schema covers parameters well. However, there is no output schema and the description does not specify what the preview consists of or how it is returned, which is a notable gap for a draft-generation tool.

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

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

Schema description coverage is 100%, so the parameters are already fully documented in the schema. The description does not add parameter-specific semantics, but it does not need to; the baseline of 3 applies because the schema carries the load.

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, 'Draft a poll', and immediately clarifies 'Does not send', making the boundary of the tool explicit. This clearly distinguishes it from sibling tools like send_message and 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 gives explicit workflow guidance: 'Show the preview; after the user says yes, call confirm_send.' It also tells the agent when not to treat this as a send operation, and explains how to interpret poll results using read_messages and get_message.

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

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

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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: nothing is sent to WhatsApp, the contact never sees it, the phone is unchanged, and empty field values delete keys. It also clarifies that remove_tags/remove_fields take keys away. This goes 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?

The description is compact yet information-dense. Every sentence earns its place: purpose, search integration, privacy guarantee, deletion semantics, and usage constraint. It is front-loaded with the core purpose and uses concrete examples ('client', 'echipa', {'role': 'contabil'}) to illustrate without bloat.

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 tool with 6 parameters, 100% schema coverage, and no output schema, the description covers all essential context: what the tool does, how it integrates with search, privacy implications, deletion behavior, and the minimum-edit requirement. The annotations cover idempotency and non-destructiveness. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaning by explaining the purpose of tags and fields (how they resolve in search_contacts), the deletion semantics for empty values, and the requirement to pass at least one edit. This complements the schema rather than repeating it.

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

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

The description clearly states the tool's purpose: file local, searchable details on a person via tags and key-value fields. It uses specific verbs ('file', 'set', 'delete') and distinguishes itself from related tools like search_contacts and remove_tags/remove_fields. The title 'Tag and annotate a contact' reinforces the purpose without being a tautology.

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 explicitly explains when to use this tool: to add searchable metadata to a contact, and how it relates to search_contacts ('this is how 'the accountant' or 'all suppliers' resolve later'). It also states constraints: pass at least one of the four edits, and the person need not be a saved contact. This provides clear usage context and differentiates from siblings.

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

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

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.