Spun WhatsApp MCP

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

The annotations already declare this is a non-read, non-destructive, non-idempotent, closed-world write. The description adds genuinely new behavior the annotations cannot express: visibility is internal only and nothing reaches the customer, plus the scope needed to call it. The notable gap is that idempotentHint=false is never surfaced — the agent is not warned that a retry could post a duplicate comment.

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

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

Two short sentences, front-loaded with what the tool does and the visibility constraint before the scope/sibling context. Every clause conveys distinct information; there is no restatement of the title 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?

Return values need not be explained because an output schema exists, and annotations carry the safety profile, so the description covers the remaining essentials: audience, permission scope, and relationship to update_task. It is slightly incomplete in leaving parameter formats and duplicate-on-retry behavior unaddressed for a write 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 0% and the description says nothing about either parameter, so it compensates for none of the gap. It never mentions that task_id must be a numeric string or that body is capped at 4000 characters and is required and non-empty. Only the self-evident parameter names carry any meaning.

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 pairs a specific verb with a specific resource ("Add an internal comment to a task") and pins down the audience (team-only in the Spun app, never sent to a customer). It also contrasts the operation with update_task on the same object, so the agent can separate it from delete/edit-style task operations. It does not explicitly name list_task_comments as the read counterpart, which keeps it just short of a 5.

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

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

The description gives the operative precondition (requires the manage_tasks scope) and frames commenting as a lighter-weight write than update_task, which is a usable selection hint between the two. It stops short of stating exclusions, e.g. when a comment is inappropriate versus a task update or a customer-facing reply via draft_reply.

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 idempotentHint=true and destructiveHint=false, and the description adds concrete meaning on top: no-op when reassigning the same member, ambiguous names return candidates rather than guessing, and the response reports previous and new assignee. It omits permission requirements and what happens on an invalid or unknown conversation_id, which keeps it from 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?

Four short sentences, front-loaded with the action and the preferred parameter, then edge-case behavior, then return value. Nothing is redundant and no sentence could be dropped without losing information.

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

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

The tool is a simple three-parameter mutation with annotations and an output schema, and the description covers the key behaviors including idempotency and ambiguous-name handling. It is close to complete but leaves out authorization scope (who may assign to whom) and the constraint that at least one assignee field must be supplied.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does explain the member_id-vs-member_name preference and the name-resolution fallback. However, it never states that one of member_id or member_name is effectively required (only conversation_id is marked required in the schema), nor that the identifiers are numeric strings, leaving a real ambiguity an agent could trip on.

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

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

The description uses a specific verb and resource ("Assign a conversation to a team member") and immediately names the two addressing modes, so an agent can distinguish it from get_conversation or list_conversations 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?

It gives clear in-tool guidance: prefer member_id over member_name, and what happens when a name is ambiguous. It stops short of naming sibling alternatives (e.g. using get_conversation first to resolve IDs) or stating prerequisites, so it is strong but not fully explicit about when/when-not to use it.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the 'Idempotent' sentence largely restates structured data. It does add one genuinely new detail: that the call succeeds and reports 'already_completed' rather than erroring, which is useful behavior 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?

Two short sentences, action front-loaded, and the idempotency behavior immediately after. No filler or redundancy in wording.

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

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

An output schema exists, so return shape need not be explained, and the annotations carry the safety profile. However, the expected_version parameter is a meaningful mutation-control feature left unexplained, which is a real gap for a state-changing 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 0% for two parameters. The description explains nothing about task_id's numeric-string format or, more importantly, the optional expected_version optimistic-concurrency guard, whose semantics (what happens on a version mismatch) are entirely undocumented.

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 ('Mark a task done'), which is clearly distinguishable from siblings like update_task or get_task. It does not explicitly name the alternative for changing a task's status, so it falls just short of a 5.

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

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

The intended action is implied by the name and the phrase 'Mark a task done', but there is no explicit guidance on when to prefer this over update_task for a status change, nor on any preconditions (e.g. permissions, whether the task must be assigned to the caller).

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=false, destructiveHint=false, openWorldHint=false), so the description's added value is the failure contract — already_exists plus data.existing_label_id in the error payload — and the semantic restriction that the created label can never be an AI send-block or AI-protected label. That is real behavior beyond the structured fields; only the idempotentHint nuance (a repeat call fails rather than no-ops) is left implicit.

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

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

Three short sentences, front-loaded with purpose and constraints, each carrying information. The final sentence on AI label exclusion is a niche caveat but earns its place by preventing a wrong assumption about what gets created.

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

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

For a three-parameter mutation with an output schema (so return values need no explanation) and full annotation coverage, this is nearly complete. The gaps are the undocumented 'description' parameter and the name-length bound, both of which the schema states only structurally.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It does explain name uniqueness and that color is a palette index 0-9 (the schema only gives min/max 0-9 without meaning), but it says nothing about the third parameter, 'description', nor about the 80-character name limit.

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 ('Create a new label') and immediately bounds it with two constraints (org-unique name, color as a 0-9 palette index). It is clearly distinct from the list_labels and update_labels siblings, though it never names them explicitly.

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

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

Usage is implied rather than stated: the agent learns that duplicate names are rejected with already_exists, which tells it to check existence first, but the description never says when to call this versus update_labels or how to recover (it does point at data.existing_label_id). No explicit alternatives or preconditions are given.

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 (mutation, non-idempotent, non-destructive, closed-world), so the description's job is to add what they cannot. It does: it discloses the duplicate-name conflict failure mode and redirects to list_projects, which is exactly the kind of runtime behavior an agent needs. It doesn't mention permission requirements or whether the creator becomes owner, 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?

Three short sentences with zero filler, front-loading the action, then the failure mode, then the dependency rationale. Every sentence carries distinct information.

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

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

For a two-parameter mutation tool with full annotations and an output schema, the description covers purpose, conflict behavior, and the cross-tool dependency, so the essential call-time knowledge is present. Only minor gaps remain, such as ownership semantics and whether the conflicting check is case-sensitive.

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

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

Schema coverage is 0%, but with only two self-describing fields (name, description) the burden is light. The description does add real semantics for name — it must be unique among active projects and conflicts are reported — but says nothing about how description is used or whether the name can collide with archived projects.

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?

"Create a shared task project" gives a specific verb plus resource, and the remainder of the description ties it to distinct siblings: list_projects for inspection and create_task for the downstream need. An agent can tell this apart from list_projects or update_task 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?

Usage is explicitly conditioned: call it when no suitable project exists, check list_projects when a name may already be taken, and it exists to unblock create_task. That names both the alternative and the selection condition rather than leaving it to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and closed-world scope. The description adds genuine behavior the annotations don't: the absence of a default project and the default assignment of responsible_member_id to the org's primary manager. It does not say whether duplicate tasks are created on retry (relevant given idempotentHint=false) or what validation failures look like.

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 compact sentences with the hard constraint (required project_id, no default) front-loaded, then the default assignee, then optional links. No filler, though it reads as a run-on list rather than clearly separated points.

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 non-destructive create with annotations covering the safety profile and an output schema covering return values, the description supplies the key operational facts: required project scoping, the default assignee, and optional association fields. Remaining gaps (priority semantics, due-date format) are minor given the self-describing parameter names.

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

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

Schema description coverage is 0%, so the schema itself only conveys types, patterns, and one enum. The description compensates for the most error-prone parameters (project_id sourcing, responsible_member_id default, optional conversation/contact links) but says nothing about title, due_date format, priority levels, or description limits, leaving half the surface undocumented.

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

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

Opens with a specific verb+resource: 'Create a task in a shared project.' That distinguishes it from get_task, list_tasks and update_task in the sibling set, though it never names those alternatives explicitly.

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

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

Gives a concrete prerequisite chain ('project_id is REQUIRED - there is no default project; project ids come from list_projects'), which routes the agent to list_projects before calling. It stops short of saying when to prefer this over update_task or create_project, but the create-vs-update distinction is largely implied by the name.

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 a non-read-only, non-destructive, non-idempotent, closed-world operation; the description adds real context on top by disclosing that a durable draft is persisted, a draft_id is returned, nothing is sent, and the call consumes the org's AI token budget. It doesn't address retry behavior (e.g. whether a repeated call creates a second draft) or failure modes, which keeps it from 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 tight sentences with the action and its inputs first, then the persistence/never-sends guarantee, then cost — no filler and nothing buried.

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

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

With an output schema present, return details needn't be restated, and the description still flags draft_id and the safety/cost profile, so an agent can call it correctly. The remaining gap is edge behavior — what happens with an invalid conversation, missing AI configuration, or budget exhaustion.

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

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

Schema description coverage is 0%, so the description has to carry the burden; it explains that 'instruction' is an optional free-text steer for the draft, which is genuinely useful. However, it says nothing about the conversation_id format constraint (numeric pattern) or the 500-character cap on instruction, leaving part of the gap for the schema alone.

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

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

The description names a specific verb and resource (draft a reply for a conversation) and qualifies the mechanism — org AI tone, presets, knowledge context — which separates it from read-only siblings like list_messages or get_conversation. It also states the output artifact (draft_id) and rules out sending, so an agent knows exactly what it gets.

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 makes the use case clear: produce a draft for human review in the inbox, with an optional instruction to steer it. There are no explicit when-not conditions or named alternative tools, but the 'NEVER sends' clause effectively defines the boundary between this tool and any send 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 read-only, idempotent, non-destructive, closed-world behavior, so the description only needs to add context, and it does: a 180-day lookback window, result sampling ('shows a few chats with the message and its neighbours'), and an explicit 'nothing is linked' statement so the agent knows the inferred identity is not persisted. The untrusted-content warning is also actionable. It stops short of 5 because the sampling limit is vague ('a few') and the return shape is left entirely to the 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?

The 180-day scope and the grouped-by-contact framing are front-loaded, and nearly every sentence carries information that changes how the agent interprets results. The identity-evidence sentence is convoluted enough to require a second read, and the branch list could have been compressed, but there is 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 an output schema present, return values need not be described, and the description covers the time window, the grouping, the sampling behavior, the no-side-effects guarantee, and prompt-injection safety. The only real gap is the absence of any pointer to the sibling search tools for the plain message-search case.

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 a baseline of 3 would be defensible, but the description genuinely adds meaning the schema lacks: it explains what the result set becomes under each chat_id variant, which the schema only gestures at. The phrase parameter's case-insensitivity and length bounds remain schema-only, which is fine.

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 clause states a specific resource and filter: chats containing an exact phrase within the last 180 days, grouped by contact. That is far more precise than the name alone and conveys the unusual identity-linking angle. It never names a sibling, though, so an agent choosing between this and search_messages_and_contacts or list_messages must infer the distinction from the identity-grouping 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 three chat_id branches are spelled out explicitly (no chat_id = every one-to-one chat; hidden-number chat_id = the other chats; normal chat_id = hidden-number chats not linked to its contact), which is genuine usage guidance for the parameter's modes. What is missing is any statement of when to prefer this tool over the search siblings, or any exclusion beyond the implicit one-to-one scope.

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 closed-world, so the safety profile is covered. The description adds that the response bundles live state (open approval requests) and a deterministic prompt review, which is useful context, but it discloses no behavior beyond payload contents and that payload is also described by the 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?

A single dense sentence, front-loaded with the core statement and then the field inventory, with no filler. The field list is long enough to be slightly list-like but each item earns its place by previewing the response.

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 one parameter, a full output schema, and complete annotations, the description covers what an agent needs to call this correctly. Return-value explanation is largely delegated to the output schema as intended, leaving only minor gaps around when the two id forms differ in behavior.

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

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

Schema description coverage is 0%, so the description must carry the parameter, and it does: 'default' selects the organization chatbot while any other value is a rule bot id sourced from list_bots. That is real semantic meaning beyond the bare regex pattern, missing only a note that rule bot ids are numeric.

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?

"One bot in full" plus an enumeration of exactly what is returned (persona, rule and trigger, on/off state, open approval requests, prompt review) makes the retrieval target unambiguous. It also implicitly separates itself from list_bots by referencing it as the id source, though the verb itself is elided rather than stated.

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

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

The description tells the agent where to get the id (list_bots) and the special 'default' value, which implies the use case of fetching one bot's details. It never states explicitly when to prefer this over list_bots or list_bot_conversations, so the routing is inferred rather than stated.

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

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

Goes well beyond the annotations by disclosing ordering (newest first), the required permission scopes (read_bots, read_conversations), the MCP conversation-scope behavior, and a prompt-injection warning that both message sides are untrusted. These are meaningful operational and safety facts the agent cannot get from readOnlyHint/idempotentHint. It stops short of explaining pagination for reaching older turns past the limit.

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?

Content is front-loaded: what is returned, then its ordering, then the trust warning and prerequisites. Every clause adds information. The opening phrase 'The AI bot exchanges in one conversation' is slightly awkward but does not cost clarity.

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

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

An output schema exists, so return-format detail is not owed here, and the description still covers ordering, scope, permissions, and content trust. Missing pieces are pagination behavior for older history and any hint on obtaining a valid conversation_id, both minor for a two-parameter read tool.

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

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

Schema description coverage is 0%, so the description carries the burden. It conveys that a single conversation is targeted (conversation_id) and that results come newest first, which gives context for limit. But it never explains limit's range (1-50), its default, or that conversation_id is a numeric string, so the parameters remain largely undocumented.

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?

Names a specific resource (the bot transcript of one conversation) and describes its shape: customer message and bot answer per turn, ordered newest first. That distinguishes it from generic siblings like get_conversation or list_messages, though it does not explicitly name those alternatives. The purpose ('for reviewing how a bot behaves') 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?

The phrase 'for reviewing how a bot behaves' implies the use case, so an agent can infer intent. However, there is no explicit when-to-use / when-not-to-use guidance and no routing to siblings such as list_bot_conversations (to find a conversation_id) or get_conversation (for the full human conversation). Usage is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real context beyond them: it explicitly scopes the output to counts only with no message content, and notes that conversation counts are filtered by org AI access settings — a non-obvious behavioral caveat that affects interpretation of the numbers.

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 summary label and then the enumerated contents. The long comma list is dense but each element maps to a distinct metric; the trailing caveat sentences are short and each 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 tool is a zero-arg read with an output schema, so return-value detail is not required. The description fully enumerates what fields to expect and flags the AI-access filtering caveat, leaving only minor gaps around latency or freshness of the counts.

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 are zero parameters, so the baseline is 4. The description correctly does not waste words on inputs and instead spends its budget describing the aggregate contents, which is the right trade-off for a no-arg tool.

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?

Names a specific resource (business snapshot) and enumerates exactly what is aggregated: conversation/message counts, contacts, active campaigns, open and overdue tasks, new signals, due alarms, pending scheduled messages, and per-channel WhatsApp connection status. Clearly distinguishes itself from siblings like get_period_report, get_usage_summary, and get_message_stats as a single-call dashboard rather than a parameterized report.

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 'aggregate business snapshot' framing implies usage (a quick at-a-glance dashboard) but never states when to use this versus get_period_report or get_message_stats, nor any prerequisites such as requiring an org context. Usage is inferable from the enumeration rather than explicit.

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

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

Annotations already declare readOnlyHint and idempotent, but the description adds substantial context beyond them: agents may not change a human_locked link, conflicts are read-only for agents, likely_match is a hint rather than an answer, and names/message text are untrusted customer content that must not be followed as instructions. The prompt-injection warning is genuinely valuable behavioral 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?

The payload description is front-loaded in the first sentence, followed by short, purposeful caveat sentences. It is dense with domain jargon and the first sentence is long, but 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?

An output schema exists, so return shape need not be described; instead the description explains what the key fields mean and how to interpret them (likely_match, human_locked, tombstone_id/link_version). Combined with the untrusted-content warning, an agent has everything needed to call 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?

There is only one parameter and schema coverage is 100%, with the schema already stating 'The hidden-number chat id, ending in @lid.' The description restates the @lid constraint and adds the 'hidden-number' framing, but contributes no new format or sourcing detail. Baseline 3 applies when the schema carries the full burden.

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

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

The description names the specific resource (the identity panel of one hidden-number chat ending in @lid) and enumerates exactly what the panel contains: identity_state, provenance, confidence, human_locked, suppressions, open conflicts, open proposals, tombstone_id, link_version. This clearly separates it from sibling list tools such as list_identity_candidates and list_identity_decisions.

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 rather than stated: the mention that tombstone_id and link_version are 'what a later link or unlink must carry' signals this is a pre-mutation read, and 'reads only' limits scope. However, there is no explicit 'use this instead of' routing to siblings like get_contact or list_identity_candidates, and no stated precondition for calling it.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real value beyond them: it defines null as "not set" and explains that translate_outgoing_to, record_voice_in and send_voice_in are per-signed-in-person fields that go null with personal_settings_available=false when there is no signed-in user.

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

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

Two tight sentences with no filler: the read/scope statement comes first, followed by the two interpretation rules an agent actually needs. Every clause carries information about return semantics.

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

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

An output schema exists, so the description needn't enumerate returned fields, and it correctly spends its budget on the non-obvious part (per-user fields and null semantics). The remaining gap is the missing routing hint toward set_chat_language_settings for mutations.

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

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

Schema coverage is 0%, so chat_id is documented nowhere, and the description only conveys indirectly that it identifies "one chat" (minLength 3 / maxLength 64 constraints are unaddressed). It does not say whether chat_id is numeric, an external key, or where to obtain it, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource ("Read one chat's language and voice settings") plus the exact frame of reference ("as the chat language panel shows them"), and scopes it to a single chat. An agent can tell this apart from the write-side sibling 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?

Usage is only implied: the word "Read" and the readOnlyHint signal a lookup, but there is no explicit when-to-use statement and no pointer to set_chat_language_settings as the mutation counterpart. Guidance on interpreting nulls is present, but guidance on choosing this tool over its sibling is not.

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 real behavioral context: it serves only STORED results and never recomputes or triggers AI work, it describes the ambiguous-lookup fallback, and it warns that digest content is untrusted customer-derived data rather than instructions. Those are traits no annotation conveys.

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

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

Front-loaded with the core action and payload, then addressing rules, then the untrusted-data caveat. Three dense sentences with little waste, though the middle addressing sentence packs several conditions into a long clause.

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

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

For a zero-required-parameter read tool with an output schema, the description covers purpose, addressing semantics, non-recomputation behavior, disambiguation fallback, and a safety note on untrusted content. The output schema handles return-value detail, so nothing essential is missing.

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

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

With 0% schema description coverage, the description carries the parameter burden and does so well, explaining the distinct roles of definition_id, name, and chat_id and the conditional behavior when only chat_id is supplied. It does not address what happens if both definition_id and name are given, nor chat_id format expectations.

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 ('Read a chat digest's prepared answer') and enumerates exactly what the payload contains (answer, key points, evidence with message ids, entities, freshness, coverage counts). This clearly separates it from sibling list_chat_summaries, which enumerates rather than returns a prepared digest.

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

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

Gives concrete addressing rules: use definition_id or name to target a definition, and chat_id alone works only when the chat has exactly one definition, otherwise matches are returned for disambiguation. It also points to list_messages for evidence sources. It does not explicitly say when to prefer this over list_chat_summaries, which keeps it short of a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the description's extra burden is lower. It still adds value beyond them: the response includes linked groups, and it warns that community and group names are third-party content to treat as data rather than instructions — a real behavioral caution an agent would otherwise miss.

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 scope and read-only nature, followed by the safety note and the next-step routing. No sentence is redundant or 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 one required parameter, an output schema that covers return values, and full annotation coverage, the description supplies everything else an agent needs: scope, safety handling of untrusted names, and where to go for group messages.

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 only one parameter and schema coverage is 100%, with the schema already saying 'Community id from list_communities' plus a pattern and length bounds. The description adds no format or sourcing 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?

The first sentence gives a specific verb and resource ('Read one WhatsApp community's details and its linked groups'), and the singular 'one' plus the linked-groups scope distinguishes it from the sibling list_communities, which enumerates communities.

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

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

It explicitly routes the agent elsewhere for a related need ('To read messages of a linked group, find its conversation via list_groups / list_conversations'), and the schema note ties the id to list_communities. It stops short of stating when not to call this tool, but the alternative path is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral context that annotations cannot: notes and labels are included, conversations are filtered to the caller's AI access scope, and the response carries a label_version token required by update_labels. It still says nothing about behavior when contact_id is unknown or out of scope.

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

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

A single dense sentence with no filler, and the resource itself is front-loaded. It is slightly run-on with three nested parenthetical clauses, but every clause carries information.

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

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

With an output schema present, the description need not explain return values, and its brief enumeration is a useful complement. For a one-parameter, read-only lookup this is close to sufficient, but the complete absence of id-sourcing and not-found behavior leaves a real operational 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 0% and the sole parameter contact_id is never mentioned in the description, so the numeric-string pattern, where to obtain an id, and what happens with an out-of-scope id are all undocumented. The description does not compensate for the schema gap at all.

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 is a noun phrase enumerating the return payload (notes, current labels, WhatsApp conversation ids) rather than stating a verb, but it does make clear that a single contact record is fetched. It never contrasts with search_contacts or search_messages_and_contacts, so the agent must infer that this is the single-record lookup rather than a search.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternative sibling (notably search_contacts, for finding a contact when the id is unknown) is named. The only usage signal is the implicit workflow hint that the returned label_version token feeds update_labels.

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 read-only and idempotent, and the description goes well beyond them: truncation signals, capped message bodies with no media, the timestamp each entry type anchors to (task completion/creation, alarm time, note last edit), access-scope exclusion of out-of-scope chats, and an explicit UNTRUSTED-content warning. These are exactly the operational facts an agent would otherwise discover only by misusing the tool.

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

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

Front-loaded with scope, then entry shape, then filters and limits, then caveats — a sensible order with no filler. The telegraphic, colon-heavy style is dense enough that a first-time reader may need a second pass, but 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 four-parameter aggregation tool with an output schema, this covers everything an agent needs: what is merged, ordering, pagination/truncation semantics, filtering, per-kind timestamp meaning, and the safety caveat about customer-authored text. No material question is left open before the call.

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

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

Schema description coverage is 0%, so the description has to carry the load, and it does: it supplies the limit default of 50 (absent from the schema, which only caps 1-200), the meaning of truncated as 'older entries exist', and the point of kinds/since as filters. It does not explain the contact_id pattern or say what since filters on (event time vs. created time), which is the one real gap.

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

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

States a specific verb and resource — 'One contact's history as one list, newest first' — and enumerates the merged kinds (messages, stage moves, tasks, alarms, notes, identity events). An agent can immediately tell this apart from get_contact (attributes), list_messages (one chat's messages) and get_conversation without opening any schema.

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

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

Gives concrete guidance: filter with kinds and since, and route to list_messages when full message text is needed. It does not explicitly state when to prefer this over get_contact or get_follow_up_queue, but the merged-history framing makes the choice obvious in most cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the optimistic-concurrency token and its role in update_labels. It says nothing about behavior on a missing or malformed conversation_id, and the output schema already covers the return shape.

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 sentence with no wasted words, and the payload/token detail is front-loaded ahead of the update_labels advice. The parenthetical is dense but functional. Minor cost: the sentence starts with a noun phrase rather than a verb, which slightly slows parsing.

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 and an output schema covering the return shape, the description needs only to explain the token's purpose and downstream use — which it does. The remaining omissions (ID origin, error behavior) are minor for a one-parameter read tool.

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

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

Schema description coverage is 0% and the single conversation_id parameter carries only a numeric pattern with no prose. The description does not compensate by explaining the ID's form or origin (e.g., where to obtain it). The parameter is self-evident enough that the gap is minor, so a 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 names a single specific resource ("One conversation") along with what it returns (current labels and a label_version token), which lets an agent distinguish it from list_conversations. It lacks an explicit retrieval verb, but the resource+payload framing makes the purpose 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?

It gives a concrete downstream use case: pass the returned label_version to update_labels as expected_version for conflict-safe label changes. That routes the agent into the read-then-update workflow. It does not state when to prefer this over list_conversations or what happens on an unknown ID, so it falls 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?

The annotations already establish that this is a safe, read-only, idempotent lookup. The description adds meaningful behavioral context beyond that: the query must use exactly one selector mode, time ranges are capped at seven days, and results can include failed, unknown, or blocked outcomes.

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

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

The description is a single dense but well-structured sentence. The core resource scope is front-loaded, followed by the selector constraints and range limit, with no redundant wording.

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

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

With an output schema and annotations already present, the description only needs to supply query semantics and constraints. It covers the critical selector exclusivity and bounded-range rules, though pagination via limit/cursor and the optional status filter are not described.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does explain request_id, idempotency_key, since, and until, including the exclusivity rule and seven-day maximum, but it leaves limit, cursor, and status filter semantics unexplained.

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 resource and scope: status of MCP-originated outbound requests, including drafts, approvals, scheduled sends, and provider outcomes. It is specific enough to distinguish this from general message or conversation tools, but it does not explicitly contrast itself with any sibling tool.

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 important usage constraints: exactly one of request_id, idempotency_key, or a bounded time range, and explicitly excludes unbounded enumeration. However, it does not explain when to use this tool versus related siblings such as list_scheduled_messages or list_messages.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety bar is met without the text. The description adds genuine behavioral value on top: it discloses that results are a merge across four heterogeneous sources and that ordering is by overdue-ness, which an agent cannot infer from the annotations. It omits pagination behavior and whether an empty result means "nothing to do" versus "no data," keeping it from a 5.

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

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

Two sentences, both front-loaded with the highest-value information: the scope and the four constituent sources come first, the ordering rule second, and the sibling disambiguation last. There is no filler and no restatement of the title.

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

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

With an output schema present, the description correctly does not spend words on return shape, and it does cover the scope, composition, and ordering that an agent needs to call it sensibly. The remaining gap is operational: default page size and how to continue via cursor are not mentioned anywhere the agent can see, since the schema documents none of it.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it only partly does. The four named sources map cleanly onto the enum values in the `sources` parameter, which is useful, but it never says that `sources` filters the merge, and it says nothing at all about `limit` (max 50) or `cursor` pagination — two of three parameters left entirely to the bare 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 resource (a merged queue) and enumerates exactly what it aggregates: awaiting-reply conversations, due alarms, overdue tasks, and new business signals. It also gives the ordering rule ("most overdue first") and explicitly names the sibling list_conversations(awaiting_reply) as covering only a subset, so an agent can distinguish it 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 frames the use case crisply as "what should I follow up on" and disambiguates against the narrowest competing sibling. It stops short of naming when NOT to use it — e.g., that list_tasks or list_business_signals should be preferred when only one source (or a full, unfiltered listing) is wanted — so the exclusion guidance covers one sibling rather than the space.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds genuinely new behavioral facts: the metadata is cached, has a freshness signal, and participant rosters are deliberately unavailable at launch. That explicit limitation disclosure is exactly the kind of context annotations cannot carry.

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

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

Two compact sentences with the resource and its returned metadata front-loaded, then the roster exclusion. The parenthetical is dense but every element (count, role, freshness) tells the agent something distinct.

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

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

An output schema exists, so return values need not be spelled out, and the description still previews the key fields and a hard limitation. The only real gap is routing guidance against the many sibling get_* tools.

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

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

Schema description coverage is 0%, so the single conversation_id parameter is undocumented in both schema and description. The description only implies it identifies a group; it does not say the value is numeric (pattern ^\d+$) or where to obtain it, e.g., from list_groups.

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

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

The description names a specific verb-resource pair ("One WhatsApp group conversation") and enumerates what comes back (participant count, your role, cache freshness), so the agent knows this is a single-group detail fetch rather than a list. It does not explicitly distinguish itself from list_groups or get_group_activity, but the singular scope differentiates it implicitly.

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

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

Usage is only implied: the required conversation_id signals "call this when you already have a group ID," but the description never says when to prefer it over list_groups, get_conversation, or get_group_activity. No exclusions or prerequisites are stated.

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

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

Annotations already cover read-only, idempotent and non-destructive, so the description's job is to add constraints — and it does: a hard 92-day window, counts-only with no message text, and that results are subject to the org's AI access and privacy settings, meaning rows can legitimately be missing or empty. Those are real behavioural facts an agent cannot get from the annotations or 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?

A single dense sentence that front-loads the resource, then the metrics, then the counting and permission caveats. No filler and no restatement of the tool name.

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

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

An output schema exists, so return shape need not be documented, and the privacy/no-text caveats are well covered. However, for a 5-parameter tool with zero schema descriptions, the unexplained sla_minutes and pagination parameters leave meaningful gaps an agent would have to guess at.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It clarifies from/to as the date range and supplies the 92-day span limit, but it says nothing about limit/cursor pagination or, critically, what sla_minutes controls (presumably the response-time threshold used to classify open requests as overdue). Three of five parameters remain opaque in both schema and description.

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 clear resource and scope: per-group activity within the organization's own WhatsApp groups, covering messages, outside requests, responses/response times and open requests, for a bounded date range. The 'per-group' qualifier implicitly separates it from get_staff_activity and get_message_stats, but no sibling is named, so an agent must infer the division of labour.

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 context is implied through the date-range framing and the 92-day cap, which tells the agent this is the bounded-window query. There is no explicit when-to-use versus get_message_stats, get_staff_activity or get_business_overview, and no statement of prerequisites or what to do when the range exceeds 92 days.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds meaningful context beyond them: data visibility is scoped by org AI access settings so numbers reconcile with other tools, and the reply-rate metric changes semantics depending on whether staff numbers are known. That conditional explanation of team_reply_rate vs sent_from_number_rate is exactly the kind of disclosure annotations cannot carry. It loses a point for not stating the failure behavior when the 92-day bound is exceeded.

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

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

Front-loads the core purpose and metric list, then layers constraints and metric caveats. Every clause carries information, but the final sentence is a dense run-on with nested parentheticals that is harder to parse than it needs to be. Slightly over-packed, though nothing is truly redundant.

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

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

With an output schema present, the description is not obliged to explain return values, and it instead spends its budget on metric definitions and visibility scoping, which is the right allocation. The only meaningful gap is the absence of any pointer to sibling reporting tools for overlapping questions, and the undefined behavior at the 92-day boundary.

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

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

Schema description coverage is 0%, so the description must compensate for two undocumented parameters. It partially does: it discloses the date range bound (max 92 days) and the timezone interpretation, but never states whether from/to are inclusive, in what order, or that they must be YYYY-MM-DD (that only exists as a regex pattern). Useful but incomplete compensation.

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: per-day message volume and reply rates over a bounded date range, listing the concrete metrics (inbound/outbound counts, active conversations, same-day reply share). An agent can distinguish it from reporting siblings like get_period_report or get_business_overview. It stops short of naming those siblings explicitly, so it lands at 4 rather than 5.

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

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

Gives real usage constraints (max 92-day window, org timezone, counts only, no content) that implicitly define when this tool applies. However, it never says when to prefer it over get_period_report, get_usage_summary, or get_business_overview, nor what to do when the range exceeds 92 days. Usage is implied rather than routed.

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 closed-world, so the safety profile is covered; the description earns credit by adding traits beyond them. It states that admin-written guidance does not override platform rules because scopes, posture and quotas are enforced server-side, and that this call is never counted against the monthly AI-call quota. The one gap is that it says nothing about caching or freshness of the returned posture/settings.

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 payload inventory is front-loaded and every clause names a distinct field, so little is wasted despite the length. It is a single dense run-on sentence, and the trailing quota-counting note would read better as its own sentence, which keeps it off 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?

An output schema exists, so return values need not be explained, yet the enumeration of the fields still helps an agent decide to call it. The description covers the two things an agent most needs to trust: that admin guidance is subordinate to server-enforced scopes and quotas, and that this call is free against quota. 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the schema-coverage baseline of 4 applies. The description correctly spends no space on inputs and instead describes the output payload.

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 concretely enumerates the resource it returns: org name and timezone, API key scopes, send posture (draft_only / two_step / autonomous), approver policy, quotas, recency and quiet-hours policy, AI scope settings, current time, and admin guidance. That is specific enough to distinguish it from siblings like get_usage_summary or get_business_overview. It stops short of a 5 because it opens with a noun phrase ('Your operating context') rather than an explicit verb-plus-resource statement of what the tool does.

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

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

It implicitly positions the tool as the place to learn 'what this key can and cannot do in this org' and explicitly routes the quota-remaining question to get_usage_summary. That is real routing guidance against a specific sibling. It does not, however, state a positive trigger such as 'call this before drafting a reply to learn the send posture', so the when-to-use case requires 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?

With annotations already covering readOnly/idempotent/non-destructive/closed-world, the description still adds substantive behavior: what a returned report contains (status, counts, sections, manifest), the resolution rule that a partial never replaces the last complete report, that results are withheld when any source chat is outside the AI read scope, and that there is no AI-credit charge. The untrusted-data warning is a useful safety cue. It stops short of describing pagination, size limits, or what an empty/absent report looks like.

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 every clause carries real information (scope, coverage semantics, access restriction, cost, safety). It is dense and slightly run-on in the coverage explanation, but there is 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 single-parameter read tool with an output schema, the definition covers resolution behavior, access restrictions, cost, and safety framing, so an agent can decide reliably whether a report will come back. The one real hole is the undocumented definition_id, which is the only required input.

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

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

Schema coverage is 0%: definition_id has no description and only a numeric-string pattern, so the description is the only place meaning could be added — yet definition_id is never mentioned. An agent must infer that it identifies which report definition to read, and nothing explains valid sources for that id.

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

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

States a specific verb and resource ("Read a stored period report") and immediately defines the exact scope: the last complete report plus, when newer, the latest attempt. That framing also implicitly separates it from list_period_reports (enumeration) and get_period_report_run (a single run) 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?

The description conveys usage context (read the current stored report, prefer the complete one over a partial) but never names an alternative tool or says when to call get_period_report_run or get_period_report_evidence instead, nor how to obtain a valid definition_id. Usage is implied rather than guided.

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, idempotent, non-destructive), it discloses that records are grouped by section, that record mode is paged by offset, that a count whose records no longer rebuild is refused rather than replaced, that there is no AI-credit charge, and that the output is untrusted customer-derived data that must not be treated as instructions. Those are genuine behavioral facts 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?

The answer to 'why this number' is front-loaded and the whole description is three sentences with no filler. Some clauses (the count-refusal and credit notes) are packed into long sentences, but each one carries information an agent needs.

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

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

Annotations already cover the safety profile and an output schema exists, so the description does not need return-value detail; it correctly focuses on mode selection, paging, refusal behavior and trust cautions. The main remaining gap is how definition_id and run_id identify a published run.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining the parameters, and it does so for count_key, section_key, record_id and offset (paging). The two required parameters, definition_id and run_id, are only implied by 'published run' and never explained directly, which leaves a real gap.

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

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

The description uses a specific verb and resource: retrieve the stored records behind one count of a published run, or a single record plus the messages it cites. The 'Why this number' framing tells an agent exactly what question this tool answers. It does not, however, differentiate itself from get_period_report or get_period_report_run, which an agent must infer from naming alone.

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

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

It gives explicit branch conditions: pass count_key (optionally with section_key) to get the records behind a count, or pass record_id to get one record with its citations. That is clear mode selection. It stops short of saying when to pick this tool over the sibling report 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the bar is lower. The description still adds real value: 'No AI-credit charge' is a billing-side-effect disclosure not captured anywhere in the structured fields, and the awaiting_credit explanation describes resumability. It does not describe how statuses progress or how costly a polled read is.

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?

Roughly three sentences, front-loaded with the verb and return payload, then the state caveat, then the call-site instruction. Every sentence carries non-redundant information; 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?

An output schema exists, so the description needn't spell out return values, and annotations cover the safety profile. For a two-parameter polling read, the main remaining hole is the unexplained definition_id/run_id pairing.

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

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

Schema description coverage is 0% for both required parameters, so the description carries the full burden and does not meet it. run_id is only implied by 'one period report run,' and definition_id is never mentioned at all, leaving an agent to guess the relationship between the two identifiers.

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 ('Read one period report run') and enumerates what it returns: status values, coverage counts and cost. It never names sibling tools like get_period_report or list_period_reports, so an agent must infer the distinction from the singular phrasing.

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

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

'Poll this after start_period_report' gives explicit when-to-use guidance tied to a concrete trigger. It also clarifies the awaiting_credit state ('resumes once credit or the limit allows'), but offers no when-not guidance or explicit comparison to the similarly named report-reading 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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds real behavioral context beyond that: the 92-day maximum window, that results are aggregate counts with no message text, and that output is filtered by the organization's AI access and privacy settings, so team phone numbers may be hidden. That last point is valuable because it explains missing or anonymized fields the agent might otherwise treat as an error.

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

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

It is a single dense sentence that front-loads scope and then lists the metrics, with no filler. The trailing privacy parenthetical earns its place by preventing misinterpretation of hidden fields. Slightly list-heavy, but nothing is redundant.

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

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

With an output schema present, the description does not need to document the return shape, yet it still summarizes the metrics, which aids tool selection. It covers the date-window constraint and the privacy caveat, leaving only the third parameter's role and any per-teammate scoping/ranking behavior 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 description coverage is 0%, so the description must carry the parameter meanings. It does define the date-range semantics (window of up to 92 days) for from/to, but never mentions group_id, leaving it unclear whether that parameter narrows the report to a single group or changes the grouping of results. Partial compensation only, hence a 3.

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

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

The description names the exact resource (per-teammate activity within the organization's own WhatsApp groups) and enumerates the returned measures: messages written, groups active in, first/last message time, median response time, and share of requests answered within 1 hour. That is far more specific than the title. It does not use a clear action verb or explicitly distinguish itself from nearby tools such as get_group_activity, get_message_stats, or get_period_report, so a 4 rather than a 5.

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

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

Usage is only implied: an agent can infer this is the tool for per-person engagement metrics, and the 92-day cap plus 'counts only; no message text' effectively rule out message-content use cases. However, there is no explicit statement of when to prefer it over get_group_activity or get_message_stats, and no prerequisites or exclusions are stated.

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

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

Annotations already declare readOnly, idempotent and closed-world, so the safety profile is covered. The description adds genuine value beyond them by disclosing a hard visibility boundary – tasks in private projects are not returned over MCP – which is exactly the kind of behavioral constraint annotations can't express.

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

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

Two short sentences, front-loaded with the payload summary and followed by the scoping caveat. Every clause carries information; nothing is 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 an output schema present, the description needn't explain return values, and it does cover the key visibility restriction. For a one-parameter read tool that is nearly complete; only the ID format caveat 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?

There is only one parameter and schema description coverage is 0%, so the description would need to compensate. It implies identifying a single task but never states that task_id must be a numeric string (the schema's ^\d+$ pattern), so an agent could plausibly pass a slug or prefixed ID.

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

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

The description names the resource (a single task) and enumerates what the response includes – fields, checklist items, comment count, recent activity – so an agent can tell it retrieves one task in full rather than a list. It gestures at the sibling relationship via 'same rule as list_tasks' but never states the verb 'retrieve' explicitly, leaving the name to carry that.

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 mention of the private-project visibility rule and its reference to list_tasks implies these two tools share scope, but it doesn't say when to call get_task versus list_tasks or update_task. Usage is inferable from 'one task in full' rather than stated.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered; the description adds genuinely new behavior — that calls here are never counted against the monthly AI quota, and that the reset date is included. That quota-exemption detail is precisely what an agent needs to decide whether calling this is free. It does not mention caching or freshness of the reported numbers, which keeps it from 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?

It is a single front-loaded sentence anchored on "Your own budget and usage," with the quota-exemption caveat placed before the usage recommendation. The stacked colon-delimited list is dense but every clause maps to a distinct return field, so little is wasted; splitting into two sentences would read better.

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

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

For a zero-parameter, read-only, closed-world tool with an output schema, the description covers everything an agent needs: what it returns, that it is free against the AI quota, and when to reach for it. Return-value detail is delegated to the output schema, which is appropriate.

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

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

The tool takes zero parameters, so there is no parameter meaning to convey and the baseline applies. The description correctly adds nothing about inputs, focusing entirely on the return contract.

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

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

The description names the exact resource ("your own budget and usage") and enumerates the concrete payload: remaining org AI-token budget, MCP rate-limit consumption per window, this API key's toolset bundles, and mcp_calls with reset date. This is clearly distinguishable from siblings like get_my_permissions or get_business_overview, which cover permissions and aggregate business metrics rather than caller-scoped quota.

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 proactive guidance: "ask here instead of guessing" and "useful ahead of large AI-compute or send workloads," which tells the agent to check quota before expensive operations. It stops short of naming a specific sibling alternative, but no plausible alternative exists for this data, so the gap is minor.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the description's job is to add context. It does: irreversibility ('permanently'), the eligible article origins, and the exclusion routing for suggestion/import articles. It stops short of stating caller permission requirements or side effects on references to the deleted article.

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, each earning its place: scope, action, eligibility exclusions, and confirmation guidance. The opening parenthetical clarification is slightly awkward as a lead-in but is genuinely load-bearing for disambiguation from search_knowledge.

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

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

An output schema exists, so return values need no explanation. For a single-parameter destructive tool, the description covers identity, irreversibility, eligibility limits, escalation path, and confirmation etiquette — everything an agent needs before invoking it.

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

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

Schema coverage is 100% with a single required source_id whose provenance is fully documented in the schema ('as returned by kb_list_articles / kb_search / kb_upsert_article'). The description adds no further meaning to the identifier, which is acceptable given the schema already carries 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?

States a specific verb and scope: 'Permanently remove one article (manual, uploaded or crawled)' from the organization's knowledge base. It also explicitly disambiguates from the sibling search_knowledge, which covers Spun's product documentation, so an agent can route between the two 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 explicit when-not conditions (articles from approved suggestions or documentation imports cannot be deleted here; a manager removes those in Knowledge Base settings) and names the alternative surface. It also adds a behavioral precondition: confirm with the person before deleting content you did not create.

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, non-destructive, closed-world behavior, so the bar is lower. The description still adds meaningful context beyond them: the full text, title and tags are returned, and the content is authored by organization members or AI connections and must be treated as untrusted — a security-relevant trait not expressed anywhere in 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?

Three tight sentences; the scope clarification is front-loaded in the parenthetical, followed by the action, then the content-description caveat. Minor redundancy between 'read one article in full' and 'complete text', but nothing wasteful.

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

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

For a one-parameter read tool with rich annotations and an output schema, everything an agent needs is present: scope boundaries, the disambiguating sibling, the shape of the returned content, and its trust level. No material gap remains.

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

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

The single parameter is documented at 100% coverage in the schema, including which tools return a valid source_id. The description only restates 'by source_id' and adds no further meaning, so the baseline of 3 applies when the schema does all 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 and resource ('Read one article in full by source_id') and immediately disambiguates scope: the organization's knowledge base, explicitly not the vendor's product documentation. That contrast with search_knowledge lets an agent pick the right sibling 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?

Clearly signals the use case (retrieve a single article in full when you have its source_id) and routes product-documentation queries to search_knowledge. It stops short of naming kb_list_articles / kb_search as the way to obtain a source_id, though the schema's parameter description does carry that pointer.

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

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

Annotations already declare readOnlyHint, idempotentHint, and closed-world behavior, so safety is covered. The description adds real context beyond that: the data source distinction (org KB vs. product docs) and the shape of each listed record (titles, tags, source type taxonomy, sizes). It stops short of describing pagination behavior or result ordering, which keeps it at 4.

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 source clarification before the operation and the sibling routing. The mid-sentence parenthetical is slightly clunky but carries essential disambiguation, so 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?

An output schema exists, so return values need not be spelled out, and the schema fully documents the filters. The one gap is that neither description nor annotations mention default page size or navigation across pages — the schema covers it only implicitly via defaults.

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 all three parameters (tag, limit, offset) carry clear inline descriptions with bounds and defaults. The description adds no filtering or pagination semantics of its own, 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?

Names a specific verb and resource ('List the articles') and scopes it to the organization's knowledge base, with a parenthetical that rules out Spun's product documentation. The returned fields (titles, tags, source type, sizes) further pin down what the operation yields, so it is unmistakable next to kb_get_article, kb_search, or search_knowledge.

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

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

Explicitly routes the agent: use search_knowledge for product documentation, kb_get_article for the text of a single article, kb_search for meaning-based lookup. Both the when-to-use and the when-not-to-use cases are stated with named 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 readOnly/idempotent/non-destructive, so the bar is low, but the description adds substantive context the annotations cannot: results are AI-drafted from customer conversations and the text is untrusted content. That is a meaningful prompt-injection warning for an agent that will subsequently read this data.

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

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

Three tight sentences, front-loaded with the corpus disambiguation before the action. The parenthetical is the only extra syntax and it earns its place by preventing a wrong-corpus call.

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

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

Output schema exists so return shape need not be explained, and annotations cover the safety profile. The description still supplies the three things structure cannot: corpus scope, the review follow-up, and the untrusted-content caveat.

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

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

Schema coverage is 100% and both parameters (limit, status) carry their own descriptions and defaults, so the schema does the heavy lifting. The description only hints at the default by saying suggestions 'await a decision,' without adding syntax or semantics beyond what is already documented.

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 knowledge suggestions) plus the defining scope: suggestions the AI assistant drafted from conversations and that await a decision. It also pre-empts the most likely confusion by naming the sibling kb_list_articles / search_knowledge territory as a different corpus.

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

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

Explicitly routes two alternatives: use search_knowledge for Spun's product documentation, and use kb_review_suggestion to act on a suggestion. It also implies the natural next step after listing, so the agent knows both the wrong path and the follow-up 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 declare mutation, idempotency and non-destructiveness; the description adds real substance by stating the tag set is replaced wholesale rather than merged, that article text is untouched, that any source type is accepted, and that re-sending the same set is a no-op. It does not cover permissions, who can edit, or whether prior tags are recoverable, so it is not fully 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?

Three tight sentences with the behavior (replace tags, don't touch text) front-loaded and the idempotency note last where it belongs. The opening parenthetical about Spun's product documentation is slightly awkward as a lead-in but earns its place as scope disambiguation.

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

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

For a two-parameter mutation with full schema coverage, an output schema and annotations, the description supplies everything left unexplained: scope (org KB vs product docs), replace-vs-merge semantics, no-op behavior, and the downstream effect on kb_search and the AI assistant. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the schema's own tag description already says 'The complete new tag set (replaces the current tags; empty array clears them)'. The description's replace semantics therefore duplicate rather than extend the schema, so the baseline 3 for fully documented parameters 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 ('Replace the tags of one article'), scopes it ('any source type') and explicitly disambiguates it from the product-documentation search tool by naming search_knowledge. An agent can distinguish this from kb_upsert_article and kb_search 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 context: for the organization knowledge base, not Spun product docs (route those to search_knowledge), and clarifies it changes tags without touching text, which implies it is the right choice when only tags need changing versus a full upsert. It never names kb_upsert_article as the alternative or states when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare it is a mutation (readOnlyHint=false) that is neither idempotent nor destructive, so the safety profile is covered. The description adds real behavioral context beyond that: approval produces a live article with optional tags, and the decision is attributed to the connected user or, for key-only connections, the organization's primary manager. It does not say whether a dismissal is recoverable or what permissions are required, which keeps it below a 5.

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

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

Two sentences, front-loaded with the scope disambiguation before the action and outcome. The parenthetical aside is a bit dense but earns its place by preventing a common misfire; no redundant restatement of the tool name.

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 three fully described parameters, an output schema, and annotations covering the mutation profile, the description supplies what structured fields cannot: the effect of each decision, tag applicability, and decision attribution. Permission requirements and post-dismissal recoverability are the only notable gaps, and neither blocks a correct invocation.

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

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

Schema description coverage is 100%, so the enum values, the tag constraints, and the suggestion_id pattern are all already documented. The description echoes 'optionally tagged' (approve only) but adds no format, ordering, or edge-case detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Decide on one pending knowledge suggestion') and spells out both branches: approve turns it into a live article, dismiss discards it. It also disambiguates the ambiguous phrase 'knowledge base' from Spun's product documentation and routes that case to search_knowledge, so an agent can distinguish this from kb_list_suggestions and kb_search 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 clear context: use this to act on a *pending* suggestion, and use search_knowledge instead when the user wants product documentation. The schema reinforces the entry point by tying suggestion_id to kb_list_suggestions. It stops short of explicit when-not guidance for this tool itself (e.g., don't use it to edit an existing article — use kb_upsert_article or kb_retag_article).

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 closed-world behavior, so the safety profile is covered. The description still adds genuine value by disclosing that matching is semantic ('search it by meaning') rather than keyword, and that results are ranked best-matching passages rather than whole articles. It stops short of mentioning ranking or threshold behavior, but the gap is modest.

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?

Sentences are front-loaded and mostly earn their place, with the disambiguation appearing early and the return shape stated plainly. The one inefficiency is that the exclusion of Spun's product documentation is stated twice, once in the opening parenthetical and again in the closing 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?

With annotations covering safety, a fully described schema and an output schema handling return structure, the description only needs to carry scope and sibling disambiguation, and it does both precisely. An agent has everything required to choose and call it correctly on the first attempt.

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 query, limit and tags are all documented in the input schema with types and bounds. The description adds no additional meaning about how the query is interpreted (natural language vs keywords) or how tags interact with the semantic search, so the baseline 3 applies.

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

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

The description names a specific verb (search) and resource (your organization's knowledge base), and immediately draws the boundary against sibling `search_knowledge` in a parenthetical. The enumerated subject matter (prices, policies, opening hours, procedures, product details) makes the content domain concrete rather than abstract.

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 when to use it (organization's own information, anything its people wrote down) and when not to (questions about how Spun itself works), naming the exact alternative tool twice. No inference is required to route between the two overlapping search 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: it explains that re-sending identical title/content/tags is a no-op with status "unchanged" (sharpening idempotentHint into concrete semantics), that overlapping content is refused with a named conflict, that changes are live for the AI assistant immediately, that creation is attributed to this AI connection, and that nothing is sent to anyone. These are exactly the mutation consequences an agent needs before writing.

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

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

Front-loaded with purpose and scoping before the behavioural details, and nearly every sentence carries information. It is dense to the point of being cramped, stacking parenthetical asides and status tokens ("unchanged", "conflict") in a single block, which slightly hurts scannability.

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

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

An output schema exists, so return values need not be explained, and the description nonetheless surfaces the two meaningful outcomes (unchanged no-op and named conflict). For a two-required-parameter upsert with an idempotency requirement, nothing an agent needs in order 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%, so the schema already documents all four parameters including tags format, length limits and source_id's role. The description only adds the nuance that source_id targets *manual* articles, which is a small but real increment over the schema wording. Baseline 3 is appropriate.

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

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

States a specific verb pair and resource — 'Create a new article ... or update an existing manual article by source_id' — and immediately rules out the confusable neighbour ('not Spun's product documentation; use search_knowledge for that'). An agent can distinguish this from kb_get_article, kb_list_articles and search_knowledge without reading any schema.

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

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

Gives explicit routing rules: use search_knowledge for product documentation instead, omit source_id to create, supply source_id to update, and on a conflict 'update that article by source_id or change the text'. When-to-use, when-not-to-use and the fallback path under rejection are all present.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so safety is covered. The description adds genuinely new behavior: results come in evaluation order, each row carries trigger/action/state/priority/cooldown/daily cap, and pagination uses an opaque cursor. Minor gap: no statement of the default page size or default active_only 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?

Three tight sentences, front-loaded with what is listed and in what order, then the get_bot caveat, then pagination. No filler and nothing repeated from the schema or annotations.

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

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

An output schema exists, so the field enumeration is a bonus rather than a requirement, and the get_bot pointer and cursor note round out a simple read tool well. The only real shortfall is that the two optional filter parameters are never explained, which leaves an agent guessing about narrowing results.

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

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

Schema description coverage is 0%, so the description carries the full burden for three parameters, but it only glosses one — cursor is called "opaque," which is useful. It says nothing about limit (bounds 1-50) or active_only, so two of three parameters remain semantically undocumented anywhere.

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

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

States a specific verb and resource ("Lists every auto-reply rule") plus the scope "all action types" and the ordering ("evaluation order"). It also distinguishes itself from get_bot by saying AI rules show the bot name rather than the persona, so an agent can tell the two apart 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 routing hint is explicit: when you need the persona behind an AI rule, use get_bot instead. What is missing is any guidance on the optional filters — nothing says when to use active_only or how many rules a typical page returns, so the agent must infer filter usage.

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, non-destructive behavior, so the bar is lower. The description nevertheless adds real value beyond them: result ordering (most recent bot reply first), per-conversation reply counts, enforcement of the organization's MCP conversation scope (channel allowlist, label scope, group toggle), and the required read_bots and read_conversations permissions. Pagination behavior is the only notable gap.

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

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

Three tight sentences: what it returns and how it is ordered, what constrains the results and what auth is needed, then the alternative tool. Nothing is redundant and the core scope statement is 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?

With an output schema present, return values need not be described, and the description covers ordering, permissions, scope filtering, defaults, and the sibling alternative. Only paging mechanics (limit/cursor) are left unaddressed for a tool that clearly paginates.

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

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

Schema description coverage is 0%, so the description carries the full burden. It fully explains the days parameter (range 1-30, default 30), but says nothing about limit (1-50 cap), cursor-based paging, or the bot_id 'default' vs numeric-id pattern. Partial compensation across four undocumented parameters warrants a middling score.

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 and resource with precise scope: conversations a bot has replied in over the last N days, ordered by most recent bot reply, with reply counts. This is clearly distinguishable from list_conversations (all conversations) and get_bot_transcript (the actual exchange), which the description explicitly routes to.

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 names an explicit alternative for the adjacent need ("Use get_bot_transcript for the exchange") and states the selection condition (bot must have replied within the window). It does not explicitly contrast with list_conversations, but the 'bot has replied in' scoping implicitly separates them.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered structurally. The description adds genuinely non-annotated behavior: a disabled chatbot_enabled flag suppresses all firing, and pending activation or change requests surface in the result. The enumeration of returned fields is somewhat redundant with the existing 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?

Three sentences, front-loaded with what is listed and scoped to the organization; no filler. The middle sentence is a long run-on enumerating result fields that the output schema already declares, which costs it a point.

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?

Zero parameters, full annotation coverage, and an output schema mean the remaining burden on the description is scope and the disabled-chatbot caveat, both of which are stated. Nothing an agent needs in order to call this correctly is missing.

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

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

The tool takes zero parameters, so the baseline applies and the description cannot add parameter meaning. It stays silent on params without misleading, which is the right call for a no-argument list operation.

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 + resource (lists the AI bots answering WhatsApp customers for this organization) with an explicit scope: the default chatbot plus every rule bot, the latter defined inline as 'an auto-reply rule with an AI persona'. It also names the sibling that covers the non-AI case, so the agent can distinguish list_bots from list_auto_reply_rules 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?

Explicitly routes the plain (non-AI) auto-reply case to list_auto_reply_rules and warns that nothing fires while chatbot_enabled is false, which is a real usage precondition. It does not say when to reach for get_bot or list_bot_conversations instead of this list, so the sibling routing is only partially covered.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world semantics, so the description's added value is the ordering guarantee ('newest first') and the prompt-injection warning that titles and summaries derive from customer messages and are UNTRUSTED — a genuinely important disclosure for an LLM consumer. It omits pagination behavior and what the response envelope looks like beyond 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?

Three compact sentences, front-loaded with the resource and ordering, then filters, then the mutation alternative, then the safety caveat. No redundant restatement of the tool name or title.

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

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

An output schema exists, so return-value explanation is not owed. For a five-parameter list tool with strong annotations, the remaining gap is pagination: cursor and limit are never mentioned, so an agent cannot infer from the description how to iterate beyond the first page.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partially does: it names the three filter dimensions (status, signal_type, urgency) but says nothing about limit (1-50) or cursor, which are the two parameters an agent must understand to page correctly. The enum values for status and urgency are only discoverable from 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 ('AI-detected business signals from monitored conversations') and grounds it with concrete examples (sales opportunities, complaints, feature requests, unanswered questions) plus ordering ('newest first'). It also implicitly separates itself from the mutation sibling by pointing to update_signal for progression.

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 tells the agent which filters are available (status, signal_type, urgency) and routes mutation intent to update_signal. It stops short of saying when NOT to use this tool (e.g., use get_business_overview or get_follow_up_queue instead for aggregate/prioritized views), so it is clear context rather than full routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the description is free to add the genuinely useful traits: results are newest-first, sourced from the platform's own call log recorded as calls happen, and metadata-only with no audio anywhere. The one gap is pagination/cursor behaviour, which is left entirely to the 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?

Three short sentences, front-loaded with the core action, then a usage cue, then a critical data-availability caveat. Nothing is redundant and nothing is buried.

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

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

With an output schema present, return values need no explaining, and annotations cover the safety profile. The description closes the non-obvious risk (an agent assuming recordings are retrievable) and flags limited log history; only cursor-based pagination semantics are unaddressed.

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

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

Schema description coverage is only 20% (missed_only is the sole documented param), so the description carries real weight. It adds intent-level meaning for missed_only ('calls that need a callback') and clarifies ordering, but says nothing about limit, since, cursor, or direction — direction and limit are mostly self-evident from their names and enum, which keeps this from dropping lower.

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 recent WhatsApp voice/video calls'), plus the ordering ('newest first') and scope ('on this account'). It is clearly distinguishable from list_messages or list_conversations, though it never names a sibling explicitly.

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

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

Gives one concrete usage cue: 'Use missed_only to find calls that need a callback.' There is no when-not guidance, no alternative tool named for broader history or per-contact lookups, and no prerequisites 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?

Newest-first ordering and the product-scope limitation add behavioral context beyond the supplied annotations. However, "Read-only" largely repeats readOnlyHint, and the description does not explain cursor-based pagination or page behavior.

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

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

Two compact sentences front-load the resource, result metadata, and ordering, then state the write-operation boundary without padding. The terse phrases "Segment messaging campaigns" and "at launch" slightly reduce immediate clarity.

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

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

The output schema and safety annotations reduce the description's burden, and the ordering and capability boundary are useful for this simple list operation. Nevertheless, the lack of any parameter documentation leaves status filtering and limit/cursor pagination underexplained.

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 0% schema description coverage, the description needed to explain the three parameters but does not identify status as a results filter or describe how limit and cursor control pagination. Its references to status and ordering provide only slight contextual help.

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 messaging campaigns as the resource and adds useful result characteristics: status and progress counts, ordered newest first. It is distinguishable from sibling list tools by resource, although the opening phrase "Segment messaging campaigns" is awkward and does not explicitly say "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?

It explicitly rules out campaign creation and control and directs those actions to the inbox UI, providing useful when-not guidance and an alternative. Positive selection guidance, such as when to use this for campaign inspection or status filtering rather than reporting tools, remains implicit.

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

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

The annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered structurally. The description adds behavior the annotations cannot convey: visibility is limited both by the API key's scope and by the org's AI channel allowlist, so results may be silently filtered. It does not discuss ordering or result size, which keeps it below 5.

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

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

Two sentences, front-loaded with what is listed and followed by the calling scenario. Every clause carries information: the org/key scoping, the channel_id workflow, and the allowlist restriction.

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-parameter read-only list with an output schema available, the description covers scope, filtering behavior, and the downstream use of the returned channel_id. The only omission is any hint about what identifying fields come back besides channel_id, which the output schema presumably supplies.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The mention of channel_id refers to an output field used by callers, not an input, so it does not inflate or detract from this dimension.

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 numbers/channels) and immediately disambiguates the domain term by equating 'channels' with 'WhatsApp numbers'. It also scopes the result set precisely ('connected to this organization', 'this key may work with'), so an agent can distinguish it from list_bots and other list_* 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?

Gives a concrete triggering scenario: call this to resolve channel_id when a send returns requires_channel on a multi-number org. That is real when-to-use guidance tied to a sibling workflow, though it names no alternative tool or explicit exclusion.

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