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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description still earns credit by disclosing that locked-chat recordings are suppressed from results and that transcripts are speaker-attributed with per-word timings. It does not cover rate limits, pagination behavior, or how missing transcripts are represented.

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 purpose, then a compact action table, then examples – a structure that is easy to scan and every block earns its place. Minor redundancy remains where the action list restates parameter names already documented in the schema.

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

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

With no output schema, the description carries the return-value burden and does it well: turns by speaker, start/end seconds, optional per-word timing, and matching lines for search. It omits any mention of target_session (multi-account routing) and result ordering/pagination semantics for search, which leaves small gaps for a 9-parameter 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, but the description adds genuine meaning beyond the schema by scoping parameters to actions (conversation_id/date_from/date_to/limit on list and search, id on get, include_words only on get) and by showing a real conversation_id format ('5491157390064@c.us') and recording id format.

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 opening sentence states a specific verb and resource ('Read WhatsApp call recordings ... and their transcripts, with every word timed') and adds the distinguishing scope that each recording links to query, get_contact and get_group. An agent can separate this from siblings like query or summarize_conversation without opening the schema.

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

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

The three actions are enumerated with the parameters each one accepts and when each is required ('requires id', 'requires search'), plus four worked examples that model typical calls. There is an explicit exclusion ('Recordings of locked chats are never returned') but no direct 'use X instead of Y' routing against siblings, which keeps this below a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely new context beyond them: the return payload is base64-encoded media plus metadata, and the input must reference a media message. It omits size limits or rate limits, so it stops short of a 5.

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

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

The what/return/precondition are front-loaded in three short lines, and the example is compact and directly actionable. The example largely repeats the schema's required fields, so it earns slightly less than full marks.

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

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

With no output schema, the description usefully discloses the return format (base64 data + metadata) and the media-only precondition. Combined with annotations and a fully described 3-parameter schema, an agent has what it needs, though routing behavior for target_session remains unexplained.

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

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

Schema coverage is 100%, so both required parameters are already documented in the schema. The description restates that message_id comes from query results but says nothing about target_session or the multi-account routing behavior, so it adds little beyond the schema baseline.

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

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

The description gives a specific verb (Download) and resource (media content) and enumerates the media kinds covered (image, video, audio, document, sticker). No sibling tool competes in this domain, so an agent can route here unambiguously.

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 a clear precondition ('The message must be a media message') and tells the agent where message_id comes from ('from query results'), which links to the query sibling. It does not name an alternative for non-media messages, but the trigger condition is explicit.

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

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

Annotations only cover readOnly/openWorld, but the description adds real behavioral detail: deduped, alphabetically sorted by display name, CSV is the default, JSON projects requested fields, and @lid privacy identifiers are always excluded. That last point is exactly the kind of non-obvious side effect the agent needs.

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 statement and the exclusion rule, then examples. The examples consume a lot of space, but each one demonstrates a distinct parameter combination rather than 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?

With no output schema, the description carries the return-value burden and does so: it names the formats, the field set, sorting, dedup, and the @lid exclusion. An agent can call this correctly without any additional information.

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 value by enumerating the six available fields and demonstrating format/fields/query/is_my_contact combinations. It goes slightly beyond the schema's own descriptions rather than merely repeating them.

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 (export all contacts) plus the output formats (CSV RFC 4180 / JSON), so the agent knows exactly what it produces. It does not, however, distinguish itself from the sibling list_contacts, which an agent could reasonably confuse it with.

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

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

Four concrete examples map intent to parameter combinations (all fields, field projection, query filtering, saved-only), which is strong implied guidance. It still never says when to prefer this over list_contacts or when not to use it, so it stops short of 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: per-section prerequisites (chat_id for chat_detail, format for exports), approximate payload size (~5KB for overview), and pagination scope — but says nothing about rate limits or export delivery mechanics.

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 one-line scope, then the workflow tip, then the section reference and examples — a sensible order. The 22-entry section list is long but each entry adds semantic detail the enum alone cannot convey, so it largely earns its space.

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

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

For a 22-mode tool with no output schema, it covers prerequisites, pagination, filtering, exports, and approximate result sizes well. It stops short of describing the shape of export output (e.g., whether a file or inline payload is returned), which is the remaining gap given no output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by mapping parameters to sections (label filter on 'activity', chat_type on 'rankings', limit on paginated sections) via worked examples. This meaningfully clarifies how the 14 optional parameters interact with the section enum.

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 ('Get WhatsApp analytics data') and enumerates the exact scope (KPIs, activity, rankings, response times, exports, growth history). An agent can distinguish this from siblings like summarize_conversation or query purely from the description.

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 entry-point guidance ('Start with section="overview" (default) ... then drill into specific sections') plus six concrete invocation examples covering filtering, chat_detail, and exports. It does not, however, say when to prefer this tool over the sibling export_contacts or query, leaving one overlap unresolved.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description contributes beyond them by disclosing the return payload (URL, auth token, available endpoints) and flagging that a credential is exposed, which is useful for a tool with no output schema.

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

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

Two tight sentences, front-loaded with the action and followed by the return contents. Every clause earns its place with no filler.

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

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

With no input parameters and no output schema, the description carries the burden of describing returns and does so by enumerating URL, token, and endpoints. It is nearly complete; a note on credential handling or endpoint format would close the remaining 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?

The tool takes zero parameters, so the baseline is 4. Schema coverage is 100% and there is nothing to document; the description correctly says nothing about inputs.

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

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

States a specific verb and resource (get HTTP REST API connection info) and explains the distinguishing value proposition of bypassing MCP overhead. No sibling tool in the list provides connection info, so an agent can immediately tell this apart from the domain tools like query or get_contact.

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

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

"For programmatic access without MCP overhead" gives a clear condition for when to reach for this tool over staying within MCP. It does not name an explicit alternative or state when-not to use it, but the triggering context is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral rule beyond the structured data — the tie-break that the saved variant wins when duplicate raw contacts share a phone — which an agent could not infer from schema or annotations.

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

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

Purpose is front-loaded, the tie-break caveat follows, and the examples come last. Three examples is slightly redundant (the bare-phone case largely repeats the leading-+ case), but nothing is wasted and the structure is easy to scan.

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 read tool with annotations covering safety, the description is largely adequate. With no output schema, however, it never describes what the returned contact contains or what happens when no match is found, which leaves a real gap for a lookup tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by explicitly confirming that either parameter alone suffices, and the dedupe tie-break clarifies how phone matching resolves when duplicates exist, plus concrete call examples.

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 ('look up a single WhatsApp contact') and names both accepted identifiers (JID or phone number). The word 'single' implicitly separates it from the sibling list_contacts, but no sibling is named outright.

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 nature of a lookup tool, and the description does clarify that either identifier parameter is valid ('both work'). However, it never states when to reach for this instead of list_contacts or export_contacts, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it reads from cached chat metadata with no network call, implying data freshness may lag reality — useful for an agent deciding whether to trust the result.

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 front-loaded sentences plus a compact example; the scoping constraint and the no-network caveat both appear before the example. 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?

Single fully-documented parameter, no output schema needed, and annotations carry the safety profile. The cache/no-network note covers the main residual concern; only the absence of explicit sibling routing keeps it short of a 5.

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

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

Schema description coverage is 100% and the schema already documents the @c.us JID format requirement. The example call reinforces the format but adds no meaning beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (WhatsApp groups) scoped to a single contact, which implicitly separates it from the sibling list_groups. However, it never names the sibling it contrasts with, so the agent must infer that distinction.

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 implies the use case (find groups a given contact is in) and gives an example call, but offers no explicit when-to-use/when-not guidance or routing to alternatives like list_groups or get_group. Usage is inferable but not stated.

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

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

Annotations cover the safety profile (readOnlyHint, openWorldHint), but the description adds real behavioral context: it forces a Store.GroupMetadata.update() round-trip against the WA backend before reading, implying freshness guarantees and added latency versus a cached read. It does not mention rate limits or failure modes, so not a 5.

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

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

Three short blocks: what it does, when to prefer it, and a concrete invocation example. The freshness guarantee is front-loaded and no sentence is filler.

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

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

For a one-parameter single-resource read with no output schema, the definition covers what is returned (current membership including recent joins/leaves), the freshness behavior, and the alternative tool. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the single jid parameter is fully documented with format constraints ('must end in @g.us'). The description's example instantiation is a minor convenience but adds no syntax or semantics beyond the schema, so the baseline 3 applies.

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

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

Specific verb (fetch) plus resource (a single group) plus a distinguishing scope qualifier: LIVE participant list. It explicitly separates itself from list_groups, so an agent can route correctly without opening either schema.

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

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

States the selection condition directly: 'Use this when accuracy matters; use `list_groups` for browsing.' The alternative tool is named and the trade-off that selects between them is 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?

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing deduplication by phone number, the sort order (saved first, then alphabetical), and the exclusion of non-dialable @lid identifiers. This tells the agent exactly what shape of data comes back and what is silently filtered out.

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 operation, then behavior, then a compact example block. Every sentence carries information and the formatting makes it 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?

With no output schema, the description carries the return-value burden and does so: dedup, ordering, and exclusion rules are all stated. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is already 100%, so the baseline is 3, but the examples add real value by showing how is_my_contact, query, and limit/offset are combined in practice (e.g., {limit: 50, offset: 50} for page 2). It stops short of documenting edge behavior such as how limit/offset interact with the deduplication pass.

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 ('List WhatsApp contacts') and immediately scopes it to the local encrypted DBR3 cache with no network. This clearly separates it from get_contact (singular lookup), export_contacts (dump), and query (search tool) among siblings.

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

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

The four worked examples cover the main invocation modes (unfiltered, saved-only, name search, pagination), which effectively communicates when to use each parameter combination. However, it never states when NOT to use this tool or points to an alternative such as get_contact for a single known contact.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: reads come from cache with no network call, implying possible staleness, and get_group forces a fresh update. Minor gap in not describing return shape or ordering.

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

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

Two sentences plus three compact examples, with the cache/network constraint and the sibling routing front-loaded. Every element earns its place; the examples are short and directly actionable.

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 two-param read tool with full schema coverage and read-only annotations, the description covers the essentials plus the cache-vs-live distinction. No output schema exists and the description doesn't sketch the returned group fields, a small remaining 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 coverage is 100%, so both parameters are documented in the schema and baseline would be 3. The concrete examples ('{ query: "family" }', '{ limit: 10 }') demonstrate how the parameters compose in practice, adding practical meaning beyond the field descriptions.

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 all WhatsApp groups the user belongs to') and explicitly distinguishes itself from the sibling get_group by contrasting cache vs live reads. An agent can route between the two without opening either schema.

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

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

Gives explicit when-to-use context (cached, no network) and names the alternative tool with the condition that selects it (live snapshot of a single group via get_group forcing GroupMetadata.update). Nothing is left to inference.

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

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

Annotations declare the safety profile (not read-only, not destructive, not idempotent, open-world), so the description doesn't need to restate it. It adds a couple of genuine behavior facts — the 3-pin cap and mute's default of 'forever' — but says nothing about permissions, reversibility, or partial-failure behavior across the ten distinct actions.

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 summary sentence followed by a compact action table; every line maps to a real enum value and earns its place. Slightly longer than strictly necessary given the schema already enumerates the actions, but the pairing of action-to-meaning is efficient.

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 5-parameter dispatcher with no output schema and full schema coverage, the description covers all action semantics and the key per-action constraints. Missing only cross-cutting details like auth/session routing for target_session and what happens on invalid action/parameter combinations.

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

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

Schema description coverage is 100%, and the two enums (action, mute_duration) are fully documented in the schema, so the baseline is 3. The description's per-action lines add only marginal meaning beyond the schema, mostly repeating the conditional requirements already stated in parameter descriptions.

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+resource ('Manage chat state') and then enumerates all ten concrete actions, so an agent knows exactly what surface this tool covers. It does not, however, distinguish itself from any sibling tool — though none of the listed siblings appear to overlap with chat-state mutation.

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?

Per-action annotations give useful constraints ('max 3 pinned', mute uses mute_duration, set_draft requires text), which is real usage guidance. But there is no statement of when to reach for this tool versus alternatives, nor any preconditions or failure conditions.

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, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine context beyond that: the WhatsApp Business account prerequisite and the per-action behavior (e.g., create vs. delete operating on different objects). It does not state that delete is irreversible, but the annotation carries that signal.

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

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

Front-loaded with the purpose and prerequisite in one line, followed by a compact action table mapping each action to its required parameters. Every line earns its place; the formatting is scannable rather than 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 4 parameters, annotations covering the safety profile, and no output schema, the description supplies the missing prerequisites and action-to-parameter mapping an agent needs to invoke correctly. Only the return/result behavior is unaddressed, a minor gap for a mutation 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 baseline is 3, but the description adds cross-parameter semantics the schema cannot express: which parameters each action requires (add/remove need label_name/label_id + conversation_id; create needs label_name). That mapping is valuable guidance beyond the per-field descriptions.

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 ('Manage WhatsApp Business labels') and then enumerates the four concrete actions (add, remove, create, delete), so an agent knows exactly what the tool does. It is clearly distinct from siblings like manage_lists, manage_notes, and manage_reminders, though it never explicitly contrasts itself with 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?

Usage is implied through the prerequisite ('Requires a WhatsApp Business account') and the per-action parameter requirements, which tell the agent how to invoke each mode. However, there is no explicit when-to-use vs. alternative guidance and no statement about which contexts call for this tool over siblings.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-structured context: the feature is account-gated and requires a probing 'list' call to detect availability. It stops short of describing deletion consequences or permission needs, but it meaningfully exceeds 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?

Front-loaded with purpose, then a compact action table where each line earns its place, then minimal examples. Slightly long overall but no filler; the action list is the core content an agent needs for a multiplexed 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 seven-action multiplexed tool with no output schema, the description documents every action's requirements and provides worked examples covering read, create, and mutation paths. Combined with full schema coverage and annotations, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description goes further by mapping each action to its required inputs (get/create/edit need name or id; add_chat needs conversation_id), which the flat schema cannot express. It doesn't clarify the single-vs-array conversation_id semantics beyond the schema, keeping it below 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+resource (manage personal chat lists) and distinguishes it precisely from the sibling manage_labels by calling it the personal-account equivalent of Business labels. An agent can tell what this tool does and how it differs 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 clear context (organizing chats into categories) and a concrete prerequisite: 'Not available on all accounts — check with action "list" first.' Each action's use is implied by its requirement list, but there is no explicit when-not-to-use guidance beyond the labeling distinction.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the write-safety profile is covered. The description adds genuinely useful context beyond that: the WhatsApp Business account requirement and that 'set' is a write/update (upsert) operation rather than an append, which matches the idempotent hint.

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

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

Two sentences plus a two-item action list; the purpose and prerequisite are front-loaded and every line earns its place. 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 small 3-parameter mutation tool with full annotation coverage and no output schema, the description covers the resource, the actions, the precondition, and the required input for 'set'. It could say what 'get' returns when no note exists or confirm that 'set' overwrites, but nothing critical 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 the baseline is 3. The description notes that the note text is required for 'set', which merely restates the schema's own 'required for "set" action' note, and it adds no format, length, or contact_id semantics.

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 (contact notes) and enumerates both supported actions (get/set) with one-line semantics, so an agent immediately knows what the tool does. It does not name or contrast any sibling (manage_labels, manage_chat) explicitly, but the notes scope is 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?

Usage is implied through the action list (read vs write a contact note) and the stated prerequisite of a WhatsApp Business account with notes enabled. There is no explicit guidance on when to prefer this over siblings such as get_contact or manage_labels, and no statement of when each action is inappropriate.

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, openWorldHint=true and idempotentHint=false, and the description usefully adds that reminders live in the cloud and fire notifications through the Kaption extension. However, it never distinguishes the safety profile of the read actions (list/get) from the destructive ones (delete), nor mentions permissions, reversibility of delete, or rate limits.

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

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

Front-loaded one-line summary followed by a scannable action table and three concrete examples; every line carries information. It is slightly redundant with the schema's own parameter descriptions, which keeps it short of a 5.

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 seven-parameter dispatch tool with no output schema, the description covers the action surface, required inputs, examples, and the notification side effect. It omits what list/get return and how errors surface, but the 100%-covered schema carries the parameter burden well.

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 including the filter and notification_type enums with defaults. The description restates the same per-action requirements and adds only format examples (ISO 8601 datetime, id shape), which is marginal added value.

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

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

The description names a specific resource ('personal reminders') and enumerates all seven operations with their required inputs, so an agent knows exactly what capability surface this tool exposes. No sibling tool touches reminders, so the scope is unambiguous within the toolset.

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 action list effectively tells the agent which operation to pick for each intent (list vs get vs create vs complete), and states per-action required parameters such as title+datetime for create. It stops short of any exclusion guidance or advice on when a reminder action is inappropriate relative to other 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?

Despite annotations already flagging destructive/openWorld, the description adds substantial behavioral detail: local-mode rate limits, 'never sent late' semantics, missed/refused request behavior with reason codes, user-only enablement, and per-action cancel/remove distinctions. This is well beyond what annotations or schema 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 text is long but justified for an 8-action, dual-mode tool. Purpose and mode trade-offs are front-loaded, and the action list plus examples each carry distinct information. Some overlap with schema parameter descriptions keeps it from a 5.

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

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

With no output schema, the description still covers behavior thoroughly and hints at list/get return shape ('each has "mode"'), plus reason codes. Given the complexity (9 params, 4 enums, 2 modes), it is nearly complete, though it does not describe the structure of list/get results in detail.

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

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

Schema coverage is 100%, so baseline is 3, but the description contributes extra meaning: which parameters each action requires, the mode-per-action constraint ('Pass mode local for every action on a local message'), and concrete example payloads with real values. It reinforces rather than merely repeats 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 opening sentence gives a specific verb+resource+scope: scheduling WhatsApp messages for automatic send at a specific time, split into two named modes. An agent can immediately distinguish this from siblings like manage_reminders or manage_chat without opening the schema.

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

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

The description gives explicit when-to-use guidance for the bot vs local modes (privacy, off-computer delivery, group support) and states the prerequisite that local mode must be enabled by the user first. It does not, however, compare against sibling tools, so it stops short of a full alternative-routing treatment.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: multi-account routing semantics (omitted target_session routes to the most recently active account) and return shape ('returns the conversation info WITH its messages'). It omits rate limits and pagination behavior, keeping it short of a 5.

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

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

Front-loaded with purpose, then sectioned under HOW TO READ MESSAGES, AUDIO TRANSCRIPTIONS, and Examples, which suits a 15-parameter polymorphic tool. The length is largely justified, though the example block restates some guidance already given in prose, adding mild 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 complex, zero-required-parameter, multi-entity tool with no output schema, the description supplies the entity model, session-routing prerequisite, and worked call shapes an agent needs. It could be more complete on return structure for non-message entities and on pagination, but nothing critical to invoking 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 baseline is 3. The description exceeds it by demonstrating parameter composition through worked examples that the schema cannot convey — e.g. that passing id alone returns a conversation with its messages, and how label vs list map to business vs personal accounts. This meaningfully reduces the chance of mis-combining the 15 optional parameters.

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

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

States a specific verb ('Query') and enumerates the exact resource set (conversations, contacts, messages, transcriptions, labels, communities) plus the operations supported (listing, searching, filtering, lookup by ID). It clearly distinguishes its internal modes, but it never differentiates itself from overlapping siblings such as list_contacts, get_contact, list_groups, or get_group, which an agent must resolve on its own.

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?

Offers unusually strong operational guidance: query entity="session" FIRST, then route via target_session, and an explicit exclusion ('Do NOT use entity="messages" for this — that is for global text search only'). The extensive example list shows when each mode applies. The gap is that it gives no guidance for choosing this tool over the overlapping sibling tools like list_contacts or get_group.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: it does not say whether summaries are cached or freshly generated, whether generation is expensive/slow, what happens when no summary exists, or whether an existing summary is overwritten when regenerated. For a dual-mode "get or generate" tool this is a meaningful gap, though it does not contradict the readOnly annotation.

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 short sentence with no padding and no buried information. It is efficient, though the brevity is partly achieved by omitting behavior rather than by tight editing.

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 the read-only/open-world profile and a fully documented schema, the remaining burden on the description is modest. Still, the get-vs-generate distinction, cost/latency implications, and any caching behavior are unaddressed, which is the one thing an agent most needs to know 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 (conversation_id, message_count, target_session) are already fully documented with defaults, bounds, and meaning. The description adds no parameter-level meaning beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

The verb+resource pair (summarize a conversation) is identifiable, and it is not confusable with siblings like get_analytics or query. However, "Get or generate" leaves a real ambiguity: it is unclear whether this is a pure read of a cached summary, a request that triggers generation, or both depending on state. That ambiguity is central to what the tool does, so this lands at minimum-viable rather than 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?

No when-to-use guidance, no when-not-to-use, and no mention of any sibling tool (e.g. get_analytics, query) that might compete for the same intent. The agent must infer that this is the right tool purely from the name.

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