HellouOne

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

Annotations already disclose that this is a non-idempotent, destructive write operation. The description adds useful context about the permission effect (agent can see and reply to conversations), but does not explain failure modes (e.g., duplicate membership) or permission requirements.

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

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

A single, well-structured sentence that front-loads the action and includes only relevant consequence. No wasted words or redundancy.

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

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

For a simple two-parameter write tool with rich annotations and no output schema, the description covers purpose and effect but leaves a gap by not mapping the parameters (especially user_id as agent ID) despite zero schema descriptions. An agent can infer the mapping but may hesitate on the user_id parameter's meaning.

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 but does not. It mentions 'agent' and 'inbox' which loosely map to the user_id and inbox_id parameters, but does not clarify that user_id is the agent's ID, nor does it explain the integer format or constraints.

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 verb (add) and resource (inbox member) and adds the effect: the agent can see and reply to conversations. It is specific enough to distinguish from most siblings, though it does not explicitly differentiate from closely related tools like remove_inbox_member or update_agents_in_inbox.

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 no guidance on when to use this tool versus alternatives such as update_agents_in_inbox (bulk updates) or remove_inbox_member. It only implies usage from the verb, with no exclusions or 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?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=false. The description adds only that the category attaches to a portal, and omits any note on non-idempotency (repeat calls create duplicates) or the destructive flag's odd fit for a create operation.

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

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

The second sentence is a near-verbatim duplicate of the first and earns no place. Two sentences deliver a single idea, so the text is redundant rather than efficiently 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?

For an 8-parameter, non-idempotent mutation tool with no output schema, the description supplies no information about the required portal_id, the effect on the portal's category ordering, or what the call returns. Annotations cover the safety profile, but the description leaves the operational picture largely unfilled.

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 eight parameters are fully documented in the schema and the baseline is 3. The phrase 'to portal' loosely ties to the required portal_id, but the description adds no syntax, format, or default information beyond the schema.

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

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

The description restates the tool name and title ('Add a new category. Add a new category to portal.') without stating anything the structured fields don't already say. It does name a verb and resource, but offers zero differentiation from siblings like update_category, delete_category, or list_categories.

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 guidance on when to use this versus update_category (existing category) or delete_category, and no prerequisites such as needing an existing portal. The only contextual hint is 'to portal,' which implies portal scoping but stops far short of when/when-not guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, non-idempotent and non-open-world, and the description adds nothing beyond them (no auth requirements, no side effects, no scope). It does not contradict the annotations, but it contributes no behavioral context of its own.

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 two sentences are redundant restatements of the same idea, which is waste rather than conciseness. Nothing is front-loaded with useful information because no useful information is present.

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

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

For a tool with nine parameters, a nested config object, no required fields, and no output schema, the description is completely inadequate. An agent learns nothing about what a valid portal creation requires or what happens on 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 100%, so the schema already documents all nine parameters (name, slug, color, config, etc.), giving a baseline of 3. The description adds no parameter meaning whatsoever, so it neither helps nor hurts beyond the schema.

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

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

The description merely restates the tool name and title: 'Add a new portal. Add a new portal to account.' It states a verb (add) and resource (portal) but offers no differentiation from siblings like update_portal, delete_portal, or list_portals, and 'to account' adds no useful scope information.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The second sentence is a near-verbatim duplicate of the first rather than a situational hint, so an agent gets no routing information.

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=true, and idempotentHint=false, so the safety profile is covered. The description adds nothing on top of that: it says nothing about required permissions, what happens if the user is already a member, or the consequences of the destructive flag. No value is added beyond 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?

A single short sentence, front-loaded with the action, with zero filler words. It is tight and well-structured, though its brevity reflects under-specification rather than genuine economy of 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 simple two-parameter add operation whose annotations already cover the safety profile, the description is minimally sufficient. Still, with 0% parameter coverage and no behavioral notes, an agent lacks the detail needed to call it confidently in edge cases (e.g., duplicate membership).

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 must carry the burden and does not. 'A person' and 'a team' loosely gesture at user_id and team_id but provide no format, constraint, or semantics; the agent learns nothing about the two integers beyond the schema types.

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

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

The sentence names a clear verb (add) and resource (person to a team), so the action is understandable. However, it is essentially a natural-language restatement of the name/title 'add_team_member' and offers no differentiation from siblings like add_inbox_member or update_agents_in_team. It sits between a vague purpose and a differentiated one.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. With siblings such as add_inbox_member, remove_team_member, and update_agents_in_team present, the agent gets nothing to help choose among 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?

Goes well beyond the destructiveHint/idempotentHint annotations, disclosing skip-aheld-phone behavior, whole-call rejection on bad phones, post-hoc do-not-call/duplicate flagging in validation_summary, the returned insert count and total, and the reassurance that it places no call. Consistent with destructiveHint=true.

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 DRAFT precondition and packs real information into every sentence with no filler. Slightly dense, but each clause earns its place.

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

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

With no output schema, the description still explains the response (inserted count and campaign total) and where validation flags surface. For a mutation tool with a precondition, that covers everything an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is a 3, but the description adds value the schema doesn't express: contact_rows and contact_ids are mutually exclusive ('one of them') and the 2000-at-a-time limit is enforced. It also clarifies phone-dedup semantics.

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

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

States a specific verb and resource (add contacts to a voice campaign) plus a hard precondition (must be DRAFT, an outbound AI campaign). Easily distinguished from siblings like remove_voice_campaign_contacts and clone_voice_campaign.

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

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

Explicitly names the when-not (not scheduled, running or archived) and provides the concrete alternative for a scheduled campaign (clone it and add to the clone), implicitly pointing at clone_voice_campaign. Nothing left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, which covers the safety profile. The description adds nothing behavioral beyond that – it does not disclose that assigning overwrites an existing assignee/team, nor the null-removes semantics, which are the important consequences a caller needs.

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

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

It is short, but the opening sentence 'Assign Conversation' is verbatim redundant with the title, wasting the front-loaded position that should carry the substantive instruction.

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

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

For a destructive mutation with no output schema, the description is too thin: it never explains the assignment semantics, overwrite behavior, or interaction between the two mutually exclusive parameters, all of which the caller must reason about. Safe profile is covered by annotations and params by the schema, but the action's consequences are not.

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 three parameters, including the null-removal behavior and the rule that team_id is ignored when assignee_id is present. The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a clear verb and resource ('assign a conversation'), and adds the target ('an agent or a team'). However, the first sentence is a pure restatement of the title, and there is no differentiation from siblings such as update_conversation or get_assignment_settings, so the agent cannot easily tell which control this tool holds.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of when to prefer this tool over update_conversation or the assignment-settings tools. The agent gets only the basic action, nothing about context or 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?

Beyond the destructive annotation, the description explains the irreversibility, that no more calls will occur, that the campaign cannot be restarted, and that contacts and results remain readable. This is exactly the behavioral context an agent needs before invoking a destructive cancel.

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 with no wasted wording. The critical permanence warning comes immediately after the verb and resource.

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 destructive tool with annotations already declaring destructiveness, the description covers the key consequences, recovery path, and data retention. Nothing essential for correct invocation appears missing.

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

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

Schema coverage is 100% and the single campaign_id parameter is documented in the schema. The description adds no additional parameter semantics, 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 gives a specific verb and resource: it CANCELs a voice campaign and explicitly limits scope to running, paused, or scheduled campaigns. It also clarifies the permanent effect and retained data, but it does not explicitly distinguish cancel_voice_campaign from the sibling delete_voice_campaign.

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

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

It clearly states the applicable campaign states and advises cloning or following up when a new campaign is needed. That gives strong usage context, though it does not explicitly say when to choose delete_voice_campaign or pause_voice_campaign instead.

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

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

Goes well beyond the destructiveHint/openWorldHint/idempotentHint annotations by disclosing recipient-level effects (unsent recipients become `unknown`, sent ones retain status), the exact error contract (422 with `reason: already_finished`), draft handling, and the admin + feature-flag auth requirements. This is exactly the extra behavioral context annotations cannot carry.

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

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

Front-loaded with the action and its permanence, then recipient effects, error behavior, draft scope, and permissions in descending order of importance. Every sentence carries distinct operational information with no filler.

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

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

For a single-parameter destructive tool with no output schema, the description covers success semantics, side effects on recipients, the failure case, and authorization requirements. Nothing an agent needs 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?

Single `id` integer parameter at 100% schema description coverage, so the schema already documents it fully. The description adds no format or sourcing detail beyond what the schema states, making the baseline 3 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?

Specific verb+resource ("Cancel a campaign") followed by a scope statement ("Ends the campaign for good") that implicitly separates it from pause/delete siblings. It never names an alternative tool, so an agent must still infer the boundary from the 'for good' phrasing.

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

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

Gives clear preconditions: admins only, `whatsapp_campaigns` feature required, drafts are cancellable, and finished/failed campaigns are rejected with 422 `already_finished`. It stops short of explicitly contrasting pause_whatsapp_campaign or delete_whatsapp_campaign as the alternatives for non-terminal outcomes.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail beyond them: the two finding categories (structural vs. policy), concrete examples of each (unreachable screen, missing footer, text over limit, card-number requests, minors targeting, mismatched category), the shape of each finding (rule, severity, JSON pointer), and the publish-gate semantics of 'publishable'.

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 front-loaded sentences, the core action stated first and the return-value detail following. The parenthetical example lists are long but each example earns its place by clarifying what counts as a structure or policy problem.

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

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

With no output schema, the description carries the return-value burden and does so well: it describes findings (rule, severity, JSON pointer) and the publishable flag. The main gap is that the required flow_id input is never explained anywhere in the definition.

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 50% — only 'fields' is documented, and flow_id carries no schema description at all. The description partially compensates by explaining what 'report' findings look like and what the 'publishable' flag means (the two enum values of 'fields'), but it never clarifies that flow_id is the required target flow identifier.

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

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

Opens with a specific verb and resource: 'Run the compliance check on a WhatsApp Flow and read the findings.' It is easily distinguished from siblings like get_whatsapp_flow (retrieval), publish_whatsapp_flow (state change), and delete_whatsapp_flow (removal).

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 statement that 'publishable' is false while any error stands implies this is a pre-publish gate, but the description never explicitly says when to call it, that it should precede publish_whatsapp_flow, or that it is read-only validation vs. a mutation. 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 flag the mutation profile (destructiveHint=true, idempotentHint=false), but the description adds crucial context annotations can't: the clone starts as a DRAFT with no contacts, no consent and no program link, and archived campaigns are acceptable sources. It stops short of explaining why the operation is flagged destructive or what happens on failure, so not a 5.

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

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

A single dense sentence front-loads what gets copied and then the follow-up workflow. Every clause earns its place, though the packed semicolon structure is slightly harder to scan than cleanly separated sentences.

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

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

No output schema exists, so the description compensates by stating 'The answer has the new campaign.' Combined with the draft state and follow-up steps, an agent has everything needed to clone and continue the workflow.

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%: campaign_id's provenance is documented and the title default ('the title plus " - Copia"') appears in the schema too. The description therefore adds nothing new about parameters, which matches the baseline 3.

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

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

States a specific verb (copy) plus exactly what is copied — AI line and settings, calling window, pacing, attempts — and what the result is (a new DRAFT). An agent can distinguish this from create_voice_campaign and update_voice_campaign without opening any schema.

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

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

Explicitly routes the caller: after cloning, add contacts with add_voice_campaign_contacts, then launch it. Also states the eligibility condition ('Any outbound AI campaign can be cloned, archived ones too'), so the agent knows which source campaigns are valid.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is supplied structurally. The description adds nothing beyond that: it doesn't clarify what a 'contactable inbox' is, whether the contact must exist, or the shape/pagination of the returned list.

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 definition is short but consists of two redundant sentences that say the same thing twice. Neither sentence earns its place, and the repetition front-loads no useful 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 read-only lookup with annotations covering safety and a fully documented schema, the description still leaves the core concept ambiguous — 'contactable inboxes' could mean inboxes the contact belongs to or inboxes that can contact them. Given no output schema, the description should carry this meaning but does not.

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 both parameters ('id' = ID of the contact, 'fields' = optional field selection) fully documented in the schema. The description contributes no syntax, format, or filtering semantics 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 description is a tautology: 'Get Contactable Inboxes. Get List of contactable Inboxes.' repeats the name/title twice with no additional detail. The only added information is the plural 'List', which weakly implies a collection return, but nothing distinguishes it from siblings like get_inbox, list_inboxes, or get_inbox_members.

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

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

No when-to-use guidance is given, and no alternatives are named despite many closely related siblings (get_inbox, get_inbox_members, list_inboxes). The agent gets no signal about when this tool is the right choice versus those.

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

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

Annotations already declare destructiveHint=true, and the description earns real credit by spelling out exactly what is destroyed: any label omitted from the payload is removed. That is materially more useful than the bare hint. One tension: 'sets the labels to exactly the list sent' describes idempotent behavior while idempotentHint is false, though this is an annotation-side issue rather than a descriptive contradiction.

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

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

Two sentences, zero redundancy, with the destructive replacement semantics front-loaded ahead of the practical keep-existing-labels tip. Nothing could be cut without losing decision-relevant information.

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

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

For a two-parameter, one-required tool with no output schema, the description covers the essential behavioral hazard. Minor gaps remain (what happens with unknown label names, whether labels must pre-exist via create_label), but nothing required for a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning the schema lacks: the labels array is a complete desired set rather than an additive list, and it explains how to construct that payload. This is exactly the kind of semantics the schema's terse 'Array of labels' entry omits.

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 ('sets the labels of a contact') and immediately corrects the misleading 'Add' in the name by clarifying it is a full replacement, not an append. It does not explicitly name the sibling it differs from (conversation_add_labels, list_all_labels_of_a_contact), but an agent can still identify the operation precisely.

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 one concrete usage rule — resend existing labels to preserve them — which effectively implies a read-then-write workflow. However it never names the alternative tool for fetching current labels (list_all_labels_of_a_contact) or states when to prefer this over the conversation-level equivalent, so routing guidance 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds nothing beyond that: no pagination behavior, no result limits, no note on how many conversations are returned or whether the list is truncated.

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

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

It is short, but the first sentence duplicates the title verbatim and earns nothing. Only the second sentence carries information, so the structure is front-loaded with waste rather than substance.

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

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

For a simple two-parameter read tool with full schema coverage and no output schema, the description is minimally viable. It nonetheless omits result volume, ordering, and pagination, which an agent listing conversations for a contact would reasonably need.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, which sets the baseline at 3. The phrase "associated to that contact" mildly reinforces that id is a contact identifier, but adds no format or syntax detail beyond what the schema provides.

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

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

The description does state a verb and resource ("Get conversations associated to that contact"), so the core purpose is identifiable. However, the opening sentence "Contact Conversations" is a pure restatement of the title, and it never distinguishes this tool from close siblings like conversation_list, conversation_filter, or get_conversation, which an agent must choose between.

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

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

There is no when-to-use guidance, no exclusions, and no mention of alternatives. With conversation_list, conversation_filter, and list_conversation_messages all present, the agent is left to guess when this contact-scoped lookup is the right choice over a general conversation query.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only that results are paginated, without saying how pagination works or what the response contains, so it contributes modestly beyond the annotations.

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

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

The definition is short and front-loaded, but the opening "Contact Filter." is pure duplication of the title and earns no place. The remaining sentence is efficient but carries very little 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 filter tool whose core complexity lives in a nested payload of attribute_key/filter_operator/query_operator conditions, the description explains none of it, and there is no output schema to fill the gap on return values. An agent would need to reverse-engineer the filter DSL from the schema alone.

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 33%: top-level page and payload have no schema descriptions, leaving the filter-payload structure and pagination semantics largely undocumented. The description's "custom filter options and pagination" loosely gestures at payload and page but adds no syntax, operator, or format detail to compensate.

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?

"Filter contacts with custom filter options and pagination" gives a verb and resource, but the leading sentence "Contact Filter." merely restates the title. It does not distinguish this tool from close siblings such as search_contacts, list_contacts, or conversation_filter, and "custom filter options" is too vague to clarify the actual capability.

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

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

There is no statement of when to use this tool versus alternatives. With search_contacts, list_contacts, and conversation_filter in the sibling set, an agent has no guidance on which one to pick or under what conditions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds no behavioral context beyond that — no note on side effects, what linking a contact to an inbox does, or whether it fails on duplicates.

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

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

The text is short but redundant — two sentences that say the same thing, with no front-loaded specifics beyond the title. It is under-specified rather than genuinely concise.

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

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

For a destructive, non-idempotent mutation with no output schema, the description should explain the effect of creating the record and any failure conditions. Annotations cover safety but the description leaves the operation's semantics 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 100% with clear descriptions for id, inbox_id, and source_id, so the schema carries parameter meaning. The description contributes nothing to parameter understanding, which is the expected baseline 3 when the schema does the heavy lifting.

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

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

The description is a tautology: 'Create contact inbox' repeats the title, and 'Create a contact inbox record for an inbox' restates the same verb+resource without added meaning. It gives no differentiation from siblings like create_contact or contactable_inboxes_get, and never explains what a 'contact inbox' record actually is.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites (e.g. that the contact and inbox must already exist), and no mention of any exclusions. The agent is left to infer everything from 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?

High-value disclosure beyond the annotations: annotations only flag destructiveHint=true, while the description explains exactly what is destroyed (any label omitted from the list) and a recovery workflow via get_conversation. Note a tension with idempotentHint=false – set-to-exactly-list semantics are arguably idempotent, so the annotation may be mislabeled, but the description itself does not misstate 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 sentences, both earning their place, with the operation's true semantics front-loaded before the recovery advice. No filler.

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

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

With no output schema and annotations covering the safety profile, the description supplies the decisive behavioral detail (replace semantics) plus a practical recovery path. Only minor gap is the absence of an alternate-tool exclusion.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real meaning on top: the 'labels' array is not additive but declarative and complete, which the schema description ('Array of labels') does not convey.

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 and then immediately corrects the misleading name: 'Sets the labels ... to exactly the list sent.' An agent can tell this is a replace operation, not an append, without opening the schema, which distinguishes it from sibling 'add_*' tools like contact_add_labels.

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 usage guidance ('send the current labels (from get_conversation) with the new ones to keep them'), naming the sibling tool that supplies the current state. It lacks an explicit when-not clause (e.g. when to use update_conversation or delete_label instead), so it stops 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — no mention of how `page` behaves (size, defaults, whether results are paged or capped) or how multiple payload conditions are combined, which is the operationally risky part of this 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?

Two short sentences with no padding, and the purpose leads. But brevity here reflects under-specification rather than economy — the content that would make it usable was never written.

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?

A read-only filter tool with a nested, order-dependent payload structure, one undescribed parameter, and no output schema, yet the description gives only a one-line restatement. It omits the pagination semantics, the filter-combination logic, and any routing versus sibling list/filter tools — an agent cannot call this correctly on the description alone.

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 33%: `page` and the top-level `payload` array are undocumented, and the payload array is precisely the semantically tricky part (an ordered list of conditions joined by query_operator). The description says 'custom filter options and pagination' but supplies no meaning beyond the field names already in the schema.

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

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

The first sentence is a verbatim restatement of the title, and the second adds only 'custom filter options and pagination' — a vague restatement of the schema rather than a clarified purpose. It names the verb+resource ('filter conversations') but does nothing to separate it from siblings like conversation_list, contact_filter, or list_all_filters.

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

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

There is no when-to-use guidance at all: no statement of when to prefer this over conversation_list or contact_filter, and no note that this reads filtered results rather than creating a saved filter (create_a_custom_filter). The agent must infer usage entirely from 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description contributes only the pagination behavior, which is thin additional context for a read-only list 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?

Two short sentences, but the first ('Conversations List') merely restates the title and earns no place. The remaining sentence is front-loaded and non-redundant, but the whole is under-specified rather than genuinely concise.

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

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

For an 8-parameter, zero-required list tool in a namespace crowded with conversation-related siblings and no output schema, the description omits what is returned, default filtering behavior (status defaults to 'open'), and how it differs from adjacent tools. Too little to call it correctly with confidence.

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 63%, in the mid band, and the description adds nothing about the parameters — it only restates pagination, which the `page` parameter already documents. Undocumented params like labels, team_id, and inbox_id get no explanatory help from the 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?

The description states a clear verb+resource ('List all the conversations') and adds scope ('with pagination'), so an agent knows it is a paginated list operation. However, it makes no attempt to distinguish itself from siblings like conversation_filter, conversation_list_meta, or list_conversation_messages, which a busy tool namespace needs.

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

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

There is no when-to-use guidance at all: no statement of when to prefer this over conversation_filter or the meta/stats variants. The agent must infer selection purely from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds some value by disclosing what the response contains (open, unassigned, and all counts), which partially compensates for the absent output schema, but it does not explain filtering behavior or how the optional filters affect the counts.

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 primary purpose. The second sentence slightly restates the title's theme but is efficient overall with no padding.

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

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

For a tool with six optional parameters, no output schema, and only 50% schema coverage, the description is too thin. It does not explain how the many filters shape the counts or clarify the mismatch between the 'unassigned' count mentioned and the absence of an 'unassigned' status enum value.

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

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

Schema description coverage is only 50%, and the description contributes nothing about the six parameters (q, fields, labels, status, team_id, inbox_id). It does not explain that the optional filters narrow which conversations are counted, so the description fails to compensate for the coverage gap.

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

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

States a specific verb (Get) and resource (Conversation Counts) and names the counts returned (open, unassigned, all), so an agent knows it returns aggregate numbers rather than a list. However, it never distinguishes itself from closely related siblings like list_all_conversation_statistics, get_conversation_report, or conversation_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?

There is no guidance on when to use this tool versus alternatives such as conversation_list (which lists conversations) or the various report/statistics tools. The agent must infer usage purely from the name and description.

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=true, idempotentHint=false, and openWorldHint=false, so the safety profile is fully covered by structured fields. The description adds nothing beyond them – no mention that creation is irreversible, that the saved query shape matters, or what identifying data is returned.

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 tool is short but the second sentence is a verbatim restatement of the first, so it does not earn its place. There is no front-loaded information of value beyond the 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?

This is a mutation tool with a nested query object, no output schema, and no explanation of what a custom filter contains or how the saved query is validated. Given that complexity and zero annotations-based disclosure of consequences, the description is insufficient for correct invocation.

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

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

Schema description coverage is 100% with three well-documented parameters (including the enum default for filter_type), so the schema carries the semantic load. The description adds no parameter meaning of its own, which is the baseline-3 case for high-coverage schemas.

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 tautology: 'Create a custom filter. Create a custom filter in the account.' It restates the tool name and title twice without adding scope, purpose, or distinction from siblings like create_macro, create_canned_response, or create_automation_rule.

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

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

There is no guidance about when to create a custom filter versus using the existing conversation_filter/contact_filter filters, nor any prerequisites, nor when to prefer update_a_custom_filter. 'In the account' is the only contextual detail and it does not help selection.

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=true, idempotentHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds nothing on top: it never mentions that message_type defaults, that private=true creates an internal note invisible to the contact, or that template_params switches to WhatsApp template delivery outside the 24-hour window. No contradiction, but zero added behavioral context.

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

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

The text is short and front-loaded, but the second sentence is a pure restatement of the first with no new information. Every sentence should earn its place, and this one does not.

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

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

For a 7-parameter, nested-object, multi-channel mutation tool with no output schema, the description is completely inadequate. It omits the private-note behavior, the WhatsApp template path and its 24-hour-window rationale, and the content_type variants, all of which materially affect 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 86%, so the schema already documents nearly all seven parameters, including the nested template_params semantics and content_type enums. The description contributes no parameter meaning at all, 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 is a near-verbatim restatement of the tool title 'Create New Message' plus the phrase 'in the conversation'. It gives no distinguishing detail against siblings such as delete_a_message, list_conversation_messages, or new_conversation. This is the tautology case rather than a clear verb+resource statement.

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

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

There is no when-to-use guidance, no prerequisites (e.g. an existing conversation, inbox channel constraints), and no mention of alternatives. The agent must infer everything from the name alone.

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=true, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: the object lands in draft state (not live), author_id defaults to the caller, and content is interpreted as markdown. It omits anything about failure modes, permission requirements, or whether repeats create duplicates, so it stops short of 5.

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

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

Three tight sentences, each delivering distinct information (what it creates, the draft/publish path, author and content semantics). Nothing is redundant with the title, and the creation fact 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?

For a six-parameter mutation with no output schema, the description covers the essential state (draft) and follow-up path (update_article), which is the highest-value missing context. It still leaves category_id unexplained and does not hint at what the call returns (e.g. the new article id) that a caller would need for the publish step.

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 17% (just portal_slug), so the description would need to carry the load for the other five parameters. It clarifies author_id semantics (defaults to you; pass an agent id from list_agents) and content format (markdown), but says nothing about title, category_id, or description constraints, leaving roughly half the parameters undocumented in both places.

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

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

States a specific verb+resource ('Create a new help center article'), which cleanly separates it from update_article, delete_article, get_article and list_articles in the sibling set. An agent knows immediately what object is produced.

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 describes the post-creation workflow and names the alternative: the article is created as a draft and publishing requires calling update_article with status published. It also routes agent-crediting through list_agents, so the agent does not have to guess at follow-up steps.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the assistant cannot create rules that call an external address or send attachments, which is a non-obvious capability 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?

Three tight sentences, front-loaded with the rule model, then the schema-pointer warning, then the hard constraint. No filler and nothing repeated from structured fields.

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

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

For a destructive create tool with no output schema, annotations plus this description give enough to invoke correctly: the rule structure, where to source ids, and what cannot be created. The only omission is whether name uniqueness or duplicate rules are enforced.

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-level coverage is only 33%, but the nested descriptions on conditions and actions are exhaustive, and the description actively directs the agent to them ('the conditions and actions schemas list the exact attribute keys... use those, not values you have seen elsewhere'). It also points at sibling list tools that supply the required ids, compensating 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 and immediately defines the tool's mental model (event + conditions → actions), which distinguishes it from sibling update_automation_rule, toggle_automation_rule, and delete_automation_rule. An agent knows exactly what this creates without opening the schema.

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

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

Gives clear operational guidance: read list_labels / list_agents / list_teams / list_inboxes for the ids and titles needed, and warns against reusing values seen elsewhere. It does not explicitly state when to prefer this over update_automation_rule, but for a create tool the context is otherwise 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=false and destructiveHint=true, so the safety profile is covered. The description adds real-world impact ('This sends messages to real customers') and explains how behavior varies by inbox type (ongoing vs scheduled one-off), which goes 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?

Four tight sentences, front-loaded with the core action and the kind-selection logic before the exclusion and prerequisite notes. Dense but every sentence earns its place; only marginally verbose.

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

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

For a destructive, non-idempotent mutation tool with no output schema and low parameter coverage, it covers the critical context: kind semantics, prerequisites, and the fact that real messages are sent. Remaining gaps are the minor boolean/string params, which are largely self-evident.

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 low (29%), so the description carries extra burden. It does clarify inbox_id's role in determining campaign kind and explains audience/scheduled_at semantics, but title, enabled, message, and trigger_only_during_business_hours remain undocumented 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 specific verb+resource ('Create a campaign') and then disambiguates by describing the two supported campaign kinds (ongoing for website inboxes, one-off for SMS inboxes). It explicitly distinguishes itself from WhatsApp campaign tools and voice campaign siblings, so an agent can select it 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 routing rules: website/SMS inboxes go here, WhatsApp campaigns do not ('composed by the administrator at Campaigns -> WhatsApp'). It also names prerequisites ('Call list_inboxes and list_labels first'), leaving little to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=true, so the safety profile is covered. The description adds no behavioral context beyond that: it doesn't say whether short_code must be unique, what happens on a duplicate, or what the call returns.

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 zero waste: purpose first, then a compact explanation of each parameter. Everything is front-loaded and earns its place.

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

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

For a simple 2-param create tool with no output schema and annotations covering the safety profile, the description covers purpose and both parameters adequately. It stops short of the operational details an agent would want (short_code uniqueness/conflict behavior, response shape).

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 compensate, and it does: short_code is defined as the text typed after '/' and content as the inserted text. That is meaningful domain semantics well beyond the bare maxLength constraints in the schema, though it omits uniqueness/format rules.

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

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

States a specific verb and resource ('Create a new canned response') and glosses the domain term as 'saved reply'. The verb makes the separation from update/delete/list canned response siblings clear, though it doesn't name an alternative 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?

No when-to-use context, no prerequisites, and no mention of the alternatives (update_canned_response, list_canned_responses). Usage is only implied by the verb, leaving the agent to infer everything about context.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false) but say nothing about data constraints. The description adds genuinely new behavioral context: email, phone_number, and identifier must each be unique within the account, which predicts conflict failures an agent must anticipate.

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 action, followed by constraints and then the sibling-exclusion. No filler and every clause carries information.

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

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

For a create tool with no output schema, the description covers the required field, uniqueness failure modes, and the scope boundary against conversations. It omits any guidance on the two nested attribute objects and on what a conflict response looks like, which keeps it from being fully complete.

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

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

Schema coverage is 50% and the description compensates partially by stating the required field and the uniqueness semantics for email, phone_number, and identifier — meaning the schema does not carry. However, custom_attributes and additional_attributes (both nested objects) are never mentioned, leaving the non-obvious parameters undocumented in both places.

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

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

The description opens with a specific verb+resource ('Create a new contact') and immediately scopes what a contact minimally requires. The closing line 'This does not start a conversation' separates it from conversation-creating siblings such as new_conversation or create_a_new_message_in_a_conversation.

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

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

It states the prerequisite (at least a name) and an explicit exclusion (does not start a conversation), which tells an agent when not to reach for it. It stops short of naming the adjacent alternatives (update_contact for edits, search_contacts for lookup), so it is clear context without full routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: attribute_key is permanent, used by filters/automations/bots, and cannot be changed afterwards - important for an agent deciding whether a key choice is safe. It stops short of explaining auth requirements or the consequence of the destructive flag.

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 purpose before the parameter clarifications. Every sentence carries weight; no filler or 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?

For a high-parameter mutation tool with no output schema, the definition covers the safety profile (via annotations) and the key immutability well, but leaves most of the 8 parameters and any return/permission detail unaddressed. It is adequate but visibly incomplete.

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 13% across 8 parameters, so the description must compensate heavily. It only clarifies two: attribute_key (format and immutability - and the format is already in the schema pattern) and attribute_values ('for a list'). regex_cue, regex_pattern, attribute_description and the enum-bearing display/model fields get no explanation.

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

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

States a specific verb and resource ('Create a new custom attribute'), which is unambiguous about the operation. It does not, however, differentiate itself from the sibling set (e.g. update_custom_attribute, delete_custom_attribute, create_a_custom_filter), leaving the agent to infer scope from the name 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?

No explicit when-to-use guidance, no prerequisites, and no mention of the update/delete siblings or the list_custom_attributes counterpart. The agent gets no help deciding between creating versus updating an existing attribute.

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

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

Annotations already declare this is a write (readOnlyHint=false), non-idempotent, and destructive, so the safety profile is covered. The description adds useful context that the document feeds the bot's answers and that a URL is crawled, but it omits ingestion timing, whether reingestion is needed before the doc is live, and any permission requirements.

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

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

Two short sentences, zero filler, and the core purpose is front-loaded before the input rule. Every clause carries information the caller needs.

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

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

For a 4-parameter, destructive create tool with 0% schema description coverage and no output schema, the description is thin: it omits the two required fields, the enum semantics, size limits, and what happens after creation. An agent would have to read the raw schema to call this correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It usefully distinguishes content (manual text) from source_url (public page to crawl) and implies mutual exclusivity, but it never mentions the two REQUIRED parameters (title, category) or explains the category enum values (faq/document/policy/other).

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 ("Add a knowledge base document") and even the effect ("the bot will answer from"), which is more than the name alone conveys. It is clearly distinguishable from siblings like get_kb_document, update_kb_document, and reingest_kb_document, 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?

The description gives one real usage rule — supply EITHER content OR a public source_url — which shapes invocation. However, it says nothing about when to reach for this tool versus update_kb_document/reingest_kb_document, nor about prerequisites such as a valid category or a reachable URL, leaving usage only implied.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=false), so the bar is lower. The description usefully adds the default behavior for show_on_sidebar and the fact that title is an identifier with a restricted charset. It does not say what happens on a duplicate title, whether the call errors or is silently accepted, or what the call returns, which are the remaining behavioral questions an agent would have.

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 purpose and then the constraints, with no filler. The trailing clause 'as in the dashboard' is a slightly ambiguous referent but does add a useful anchor for the default value.

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

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

For a create/mutation tool with no output schema, an agent still lacks the response shape (does it return the new label id?) and the duplicate-title behavior. Annotations do cover the mutation/risk profile, so this is adequate but not complete.

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

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

Schema description coverage is 0%, so the description carries the burden. It supplies the title charset rule, the color format with an example, and the show_on_sidebar default -- covering three of the four parameters. It never mentions the 'description' parameter at all, and it omits the maxLength bounds that the schema enforces, leaving a real gap against a 0%-coverage 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 opens with a specific verb+resource: 'Create a new conversation label.' That is unambiguous and easily separable from delete_label, update_label, and list_labels by name alone. It stops short of explicitly naming a sibling or scoping the tool against them, so it lands at a strong 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?

There is no guidance on when to create a label versus reusing an existing one (list_labels), nor any prerequisite such as admin permissions. The only usage-flavored content is format constraints on the inputs, which is parameter semantics, not when-to-use 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 state destructiveHint=true and readOnlyHint=false, so the agent knows this creates a resource. The description adds value by explaining the visibility semantics ('global means every agent sees it') and the prerequisite lookups for ids/labels. It does not discuss idempotency, side effects beyond creation, or rate limits, but for a creation tool the provided context is solid.

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, front-loaded sentences: definition, prerequisite lookups, visibility semantics. No redundancy or filler; every sentence delivers actionable detail.

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

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

Given the tool's complexity (nested actions, 14 action types) and lack of output schema, the description covers the critical usage pattern: what a macro is, how to resolve ids, and visibility impact. It could mention how to order actions or any limits, but the schema covers most of that. Overall complete enough for correct invocation.

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

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

Schema coverage is 67%, with the actions array carrying a detailed per-action description. The description itself does not add parameter syntax; it only points to helper tools for ids and labels. The schema already documents visibility and action_params thoroughly, so the description adds little new parameter information, but it correctly directs the agent to the right retrieval tools.

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 verb and resource (create a macro) and adds a functional definition of what a macro is: a named sequence of actions an agent runs on a conversation with one click. This distinguishes it from siblings like execute_macro or update_macro, though it could more directly contrast with those alternatives.

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

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

The description provides explicit prerequisite guidance: 'Call list_agents, list_teams or list_labels first when an action needs an id or a label.' This tells the agent when to perform preparatory steps. It does not, however, state when to use this tool versus update_macro or create_canned_response, but the action-oriented context of building a sequence 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=false, destructiveHint=true, and idempotentHint=false, so the safety profile is covered. The description adds one genuine behavioral detail beyond the schema – that names are normalized to lowercase – but says nothing about duplicate-name handling, required permissions, or side effects.

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, the operation stated first and the normalization caveat second. Nothing is padded or 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?

For a mutating, non-idempotent creation tool with no output schema and 0% schema description coverage, the definition omits too much: unclear semantics for two of three parameters, no error/duplicate behavior, and no indication of what is returned on success.

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 three parameters, so the description carries the full burden. It hints at the required name (lowercase storage) but gives no meaning for the optional description or allow_auto_assign parameters, leaving two parameters undocumented in both places.

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

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

States a specific verb and resource ("Create a team"), so an agent immediately knows the operation. It does not differentiate from siblings such as update_team or delete_team, but those names are self-evident, so the gap is minor.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as update_team or add_team_member. The agent must infer everything from the tool name alone.

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: drafts place no call, phones are validated synchronously and a bad row rejects the whole request, DNC/duplicate flags appear afterwards in validation_summary, and the response includes the campaign id used by every other voice campaign tool. The idempotency_key retry semantics sit in tension with idempotentHint=false, but the annotation is defensible (the tool is only safe to retry when the key is reused; a new key creates a second campaign), and the description resolves the ambiguity for the caller.

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 paragraph, but front-loaded with the highest-value fact (DRAFT, no calls placed) and every sentence carries operational information. It runs long and would scan better as short clauses or bullets, which keeps it from a 5.

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

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

For a 16-parameter, nested-object tool with no output schema, the description covers the essentials: contact sourcing, sync vs. async validation, idempotency, and the return shape (campaign id + contacts_import). It leaves defaults and error payload format to the schema, which is acceptable, so only minor gaps remain.

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

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

Schema coverage is 88%, so the baseline is 3. The description does add real value the schema cannot express — the mutually exclusive one-of constraint across contact_rows / contact_ids / audience_type+audience, the retry contract for idempotency_key, and where validation results surface — but it stays at the baseline rather than explaining the 16-parameter surface in depth.

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 plus a critical scope qualifier: 'Create an AI voice campaign as a DRAFT: it places no call until it is launched.' This immediately separates it from launch_voice_campaign and test_call_voice_campaign in the sibling list, and names the owning entity (AI phone line, voice_line_id).

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

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

Explicitly states contacts must be supplied in the same call and that exactly one of contact_rows / contact_ids / audience must be sent, which is the main source of misuse. It also clarifies that consent is not part of creation but is attested at launch. It does not name the launch/update siblings by name, so routing to the next step 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 readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=false, covering the safety profile. The description adds one genuinely useful behavioral fact not in annotations: the created draft is not customer-visible until published. It does not explain permission requirements, what `name` controls, or why destructiveHint is true for what reads as an additive create.

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 with the purpose front-loaded, which is efficient. However the second sentence is malformed ('...inbox named' with no object), so the structure fails at the exact point where it should be most informative.

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

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

For a mutation tool with three undocumented required parameters and no output schema, the description leaves major gaps: what `name` names, which inbox qualifies, required permissions, and what the created draft contains. The dangling clause actively withholds information the agent needs to call it correctly.

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

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

Schema description coverage is 0% for all three required parameters, so the description must carry the burden. It only obliquely gestures at template_slug ('from a gallery template') and at inbox/name via the broken phrase 'on the WhatsApp Cloud inbox named', adding almost no real semantics and no format or constraint detail.

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

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

Clear specific verb + resource: 'Open a new WhatsApp Flow draft from a gallery template', which distinguishes it from publish_whatsapp_flow, delete_whatsapp_flow, and deprecate_whatsapp_flow siblings. The trailing clause 'on the WhatsApp Cloud inbox named' is garbled and dangling, mildly hurting precision, but the core action is unmistakable.

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

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

Usage is only implied: the note that 'the draft reaches no customer until it is published' hints that a publish step follows, but no sibling (publish_whatsapp_flow, list_whatsapp_flows) is named, and there is no when-to-use or when-not guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing on top of that — it does not state that the filter is permanently removed, whether dependent automations/conversations affected, whether a confirmation is required, or how errors surface on an unknown ID. With annotations present the bar is lower, but zero additional context still caps this low.

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

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

It is short, but the second sentence is pure duplication of the first and earns no place. Appropriate conciseness here would have meant using the space for irreversibility or prerequisite information instead of repetition.

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

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

For a one-parameter delete whose annotations already flag destructiveness and idempotency and whose schema documents the only input, the definition is minimally viable. It is nonetheless missing the one thing an agent most needs for a destructive call — confirmation that deletion is permanent and unrecoverable.

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% for the single custom_filter_id parameter, so the baseline of 3 applies. The description contributes no extra meaning about the ID's expected format or origin (e.g. obtained from list_all_filters).

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 verbatim restatement of the tool name and title ('Delete a custom filter. Delete a custom filter from the account.'), which the rubric treats as tautology. The only added token 'from the account' hints at scope but does not distinguish this tool from the numerous sibling delete_* tools or from update_a_custom_filter / get_details_of_a_single_custom_filter.

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

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

No when-to-use guidance, no mention of alternatives, and no statement of prerequisites such as needing an existing filter ID or owner permissions. The agent is left to infer everything about when this call is appropriate.

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 safety and repeatability are covered. The description adds non-obvious behavioral context the annotations lack: attachments are removed along with the message, which is material for an irreversible operation.

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

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

The two sentences are duplicative ('Delete a message. Delete a message and it's attachments...'), which wastes the first sentence, and the grammar error ('it's' for 'its') slightly muddies meaning. The key detail (attachment deletion) is nevertheless front-loaded and easy to extract.

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

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

For a two-parameter mutation tool with no output schema, the annotations plus the attachment-cascade note cover the essentials. It remains incomplete on when the tool should be used, whether deletion is recoverable, and what is returned, so an agent still has gaps before calling 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 100% and both parameters are fully documented in the schema as numeric IDs, so the baseline of 3 applies. The description adds nothing about parameter meaning, format, or how to obtain the IDs.

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 (Delete) and resource (a message) and additionally discloses the cascade effect on attachments, so the agent knows exactly what is being removed. It does not differentiate itself from other delete_* siblings, though the resource name makes the distinction fairly self-evident.

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

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

There is no statement of when to use this tool versus alternatives (e.g., list_conversation_messages to locate the target message first), nor any prerequisites such as required permissions. The agent gets no routing help beyond the tool 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond them by disclosing the consequence of deletion ('losing the text') and offering the reversible alternative. It doesn't cover permission requirements or confirmation flow, 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?

Two sentences, zero waste. It front-loads the action and then immediately follows with the safer alternative, which is exactly the ordering an agent needs when weighing deletion.

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

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

For a simple two-parameter destructive tool with no output schema and full annotation coverage, the description supplies the essential missing piece: why archiving is preferable and when deletion is sanctioned. Minor gaps around permissions/confirmation remain, but nothing critical is absent.

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 50%: portal_slug is documented in the schema (with a list_portals reference) but article_id has no description. The description adds no parameter meaning, though the parameter names are largely self-explanatory, landing at the minimum-viable baseline.

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

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

States a specific verb and resource ('Delete a help center article'), and distinguishes itself from update_article by framing that tool as the non-destructive archiving path. An agent can identify the operation and its scope 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?

Explicitly names the alternative ('update_article with status archived'), explains its advantage ('keeps it out of the portal without losing the text'), and states the condition under which deletion is warranted ('unless the administrator asks for a deletion'). This is textbook when/when-not guidance.

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

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

Annotations already supply destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value on top: the hint that deletion is not recoverable and that a reversible alternative exists. It does not disclose side effects on any dependents of the rule, but that is a minor gap given the annotation coverage.

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

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

Two short sentences, zero waste, with the core action front-loaded ahead of the alternative-tool guidance.

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 destructive mutation with no output schema and annotations covering safety, the description gives purpose plus the key decision cue. It omits what happens if the ID is invalid or whether any related state is affected, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 0% for the single parameter, so the description must carry the burden of explaining automation_rule_id, and it says nothing about it. The parameter is a self-evident integer identifier with a documented type and minimum in the schema, so the omission is tolerable, but no added semantic value is provided.

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

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

The description states a specific verb ('Delete') and resource ('automation rule') and immediately contrasts itself with the sibling toggle_automation_rule. An agent can distinguish it from the many other delete_* tools without opening any schema.

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

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

It names an explicit alternative (toggle_automation_rule) and the condition that selects it ('when the administrator may want it back'), which also implies the permanence of deletion. It stops short of stating prerequisites (e.g., rule must exist, required permissions) or other when-not conditions, so it is clear context rather than a complete decision rule.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description earns credit for adding a genuine consequence beyond the annotations: existing sent messages are preserved in their conversations, clarifying the blast radius of the deletion.

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, no filler, and the core action is front-loaded ahead of the retention detail. Every sentence earns its place.

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

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

For a single-parameter destructive tool whose annotations already cover safety, the description plus schema is nearly complete. It could add whether deletion is permanent/unrecoverable, but the retention note and annotations leave little an agent genuinely needs 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 one parameter and 100% schema description coverage ('Campaign id as returned by list_campaigns'), the schema carries the full parameter burden. The description adds nothing about the id format or source, so the baseline 3 applies.

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

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

States a specific verb (Delete) and resource (a campaign) in the first sentence, which is clearer than the title alone. It does not, however, distinguish itself from the closely related siblings delete_voice_campaign and delete_whatsapp_campaign, since 'campaign' here is generic.

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

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

There is no guidance on when to use this tool versus the sibling delete_voice_campaign/delete_whatsapp_campaign variants, nor any stated prerequisite such as needing a campaign id from list_campaigns or confirming the campaign must not be active. The agent must infer the context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral context by clarifying scope: previously sent replies survive the deletion. It stops short of noting permanence or any permission requirement.

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, zero waste, with the core action stated first and the side-effect caveat second. Nothing is padded.

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

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

For a single-parameter destructive tool with a full annotation safety profile and no output schema, the description covers the essentials. The only real omission is where to obtain the canned_response_id.

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 canned_response_id — no format, no source, no note that it comes from list_canned_responses. The parameter name is largely self-explanatory, so the gap is mild rather than severe.

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 ('Delete') and resource ('a canned response'), which is unambiguous against the many other delete_* siblings since the resource differs. No explicit sibling differentiation is given, but the noun alone is discriminating enough.

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 no when-to-use context, no prerequisites, and never mentions the alternatives (update_canned_response, list_canned_responses) or when deletion is appropriate. Adoption is left entirely to inference from 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?

The annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that baseline: it does not mention whether deletion cascades to articles within the category, whether it is reversible, or what permissions are required.

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 second sentence ('Deletes a category of a portal') is redundant with the first and with the tool name, so no sentence truly earns its place. Brevity here reflects under-specification rather than effective concision.

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

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

For a destructive deletion tool with no output schema, the definition should communicate cascade behavior and irreversibility; the annotations only supply the generic destructive hint. Nothing about side effects on contained content or error conditions is provided, leaving a significant gap.

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

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

Schema description coverage is 100% and both parameters (portal_slug, category_id) are documented in the schema itself. The description adds no format, nesting, or lookup guidance 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 description restates the tool name almost verbatim ('Delete a category') and adds only the trivial scoping phrase 'of a portal', which the required portal_slug parameter already implies. It does not distinguish this operation from sibling deletes such as delete_portal, delete_label, or delete_kb_document.

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

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

There is no guidance on when to use this versus update_category, list_categories, or delete_portal, and no prerequisites or exclusions are stated. The agent must infer all usage context from the name alone.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely new behavior beyond that — cascade deletion of conversations and messages, irreversibility ('cannot be restored'), and an operational precondition (online contacts cannot be deleted). These are exactly the consequences an agent needs before calling a destructive 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?

Three short sentences, each earning its place: purpose first, then the destructive consequence, then the precondition. No filler, front-loaded with the core action.

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 destructive mutation with no output schema, the description covers purpose, cascade effects, irreversibility, and a blocking precondition — near-complete. The only minor gap is not indicating how to source a valid contact_id, which the schema also leaves unstated.

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 the single contact_id parameter and the description says nothing about parameters. The name is largely self-evident, but per the low-coverage rule the description should compensate (e.g., where to obtain the ID) and it does not add any semantic 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?

States a specific verb and resource ('Delete a contact') in the first four words, and the resource ('contact') cleanly separates it from the many sibling delete_* tools (delete_label, delete_macro, delete_team). An agent can identify what it does 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?

Usage is implied by the verb+resource rather than stated, and no alternative sibling is named (e.g., what to do instead of hard-deleting). The precondition about online contacts is a failure constraint rather than when-to-use guidance, so guidance remains partially inferred.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds a genuinely useful nuance: stored values are not erased, they simply stop being shown on conversations/contacts. That distinction matters for a destructive call and is not derivable from the annotations.

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

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

Two short sentences, action first, consequence second. No filler and nothing to trim.

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?

Adequate for a single-parameter destructive delete whose safety profile is already carried by annotations, and no output schema exists to explain. Still missing the permanence/reversibility question and how to identify the target attribute, which the 0%-coverage schema leaves entirely open.

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 never references attribute_id — no hint on where to obtain the ID (e.g., list_custom_attributes or get_details_of_a_single_custom_attribute) or what an invalid ID yields. With one undocumented parameter, the description fails to compensate for the schema 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?

Specific verb ('Delete') plus resource ('custom attribute') in the first sentence, which cleanly separates it from the sibling create_custom_attribute, update_custom_attribute, and list_custom_attributes. An agent can identify the operation without opening the schema.

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

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

No when-to-use guidance, no prerequisites (e.g., required permissions or that the attribute must exist), and no mention of update_custom_attribute as the non-destructive alternative. The consequence sentence hints at impact but does not route the agent.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds the non-obvious cascade that the indexed chunks are removed too, which is exactly the kind of consequence annotations cannot express. It stops short of stating permanence or required permissions.

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

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

One sentence, front-loaded with the verb and the primary consequence (chunk deletion). Every clause earns its place with zero 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 low-complexity, one-parameter tool with rich annotations and no output schema, the description covers what the agent needs: what is removed and what happens to the index. Missing only failure/permission context, which is minor at this complexity.

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, but it never mentions document_id. Baseline for a single trivially named required parameter with no schema prose is a 3; the name is self-explanatory but nothing in the description clarifies format or scope.

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 ("Delete a knowledge base document") with the added scope of removing its indexed chunks. It is distinguishable from the many delete_* siblings by the KB document resource, though it never names an alternative. Clear but not sibling-differentiating in prose.

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

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

No when-to-use guidance, no mention of alternatives (e.g. update_kb_document for a soft edit or reingest_kb_document to rebuild the index), and no warning about irreversibility before calling. The agent is left to infer usage entirely from 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 destructiveHint=true and idempotentHint=true, but the description adds real blast-radius context: removal propagates to every conversation carrying the label and to automations that add it. It does not state auth requirements or behavior when label_id does not exist.

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, consequence front-loaded immediately after the action, with zero filler. Every sentence earns its place.

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

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

For a destructive single-parameter delete whose annotations already flag destructiveness and idempotency, the description supplies the missing propagation semantics. Only error/not-found behavior and irreversibility wording are absent.

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 never mentions label_id at all — not its type, format, or how to obtain it. The single required parameter is 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?

States a specific verb and resource ('Delete a label') and the second sentence clarifies the effect scope. It is trivially distinguishable from create_label/update_label/list_labels by verb, 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?

There is no when-to-use or when-not-to-use guidance and no alternative named (e.g., update_label to rename instead). Usage is only implied by the verb 'delete'.

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 safety profile is covered. The description adds one useful scope fact – that past conversations the macro acted on are unaffected – but says nothing about confirmation, auth requirements, or behavior when macro_id is invalid.

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 zero filler, and the core action is front-loaded before the caveat. Every sentence earns its place.

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

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

For a single-parameter delete with no output schema, rich annotations already cover the destructive/idempotent profile and the description adds the retroactive-effect caveat. It is largely complete, missing only error/nonexistent-ID 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 parameter meaning, yet it never mentions macro_id. The schema only supplies the type and a minimum of 1; the description adds nothing about how to obtain or format the 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+resource ('Delete a macro') that clearly distinguishes it from sibling write tools like update_macro, create_macro, and execute_macro. It doesn't explicitly name those siblings as alternatives, so it falls short of a 5, but the purpose 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as update_macro or the fact that execute_macro is the runtime counterpart. The second sentence is a behavioral caveat, not usage 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing what is destroyed alongside the portal: its categories and articles (a cascade). It omits any mention of required permissions or recoverability.

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. The second sentence partially restates the first ('Delete a portal' / 'Deletes a help center portal'), but its cascade detail earns its place.

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

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

For a single-parameter destructive tool whose annotations already flag destructiveness and idempotency, the description supplies the key missing fact: the deletion cascades to categories and articles. Nothing else is strictly required given the absence of an output schema.

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

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

Schema description coverage is 100% and the single required parameter portal_slug is fully documented in the schema as the slug appearing in the help center link. The description adds no syntax or format detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb (delete) and resource (portal) and clarifies the resource as a 'help center portal'. The second sentence adds scope by naming the cascaded children (categories and articles), which effectively separates it from delete_category and delete_article. It does not, however, explicitly name a sibling it must not be confused with.

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

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

There is no guidance on when to use this tool versus alternatives, nor any precondition or warning about irreversible deletion. The agent must infer from the name and destructiveHint that this is the terminal cleanup operation.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds genuinely new behavioral detail: members retain access and conversation assignments are dropped. That is exactly the cascade information an agent needs before calling a destructive tool. It stops short of stating irreversibility or required permissions, 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?

Two short sentences, the core action front-loaded, and each clause carries distinct information (member effect, conversation effect) with zero redundancy.

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

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

For a single-parameter destructive tool with annotations covering the safety profile and no output schema, this is nearly complete: action and side effects are both stated. Only edge behavior (invalid or already-deleted team_id) is 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?

There is one parameter (team_id) with 0% schema description coverage, so the description carries the burden but says nothing about it. The integer-id name is largely self-explanatory, so this is adequate rather than deficient.

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 ('Delete a team') that an agent can immediately act on. It is clearly distinguished from update_team and remove_team_member by the verb, though the description never names those siblings 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?

The description gives no when-to-use guidance, no prerequisites, and no routing to alternatives such as update_team or remove_team_member. Usage is only inferable from the tool name itself.

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 safety profile is covered structurally. The description adds genuinely non-structured context: administrator-only authorization and the `contact_center` feature gate. It stops short of saying whether the deletion is permanent/hard or what happens to associated campaign 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?

Short and front-loaded, with the critical precondition and auth gates bolded for scannability. However, 'Deletes a campaign' restates the title and first sentence, so one of the four sentences earns nothing.

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 destructive tool with full schema coverage and complete safety annotations, the description covers preconditions, authorization, and feature gating. It does not indicate what a successful call returns (no output schema exists), but that omission is minor here.

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

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

The single parameter `display_id` is fully documented in the schema (100% coverage), and the description adds no syntax, format, or sourcing detail beyond it. Baseline 3 is appropriate 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?

Specific verb+resource ('Delete a voice campaign') that is immediately distinguishable from delete_campaign, delete_whatsapp_campaign, and cancel_voice_campaign. The second sentence is redundant ('Deletes a campaign'), but the scope constraint that follows pins the tool down precisely.

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

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

Explicitly states the precondition ('Only draft campaigns can be deleted') and routes the alternative case to a named sibling action ('end a running one with Cancel'), which maps to cancel_voice_campaign. An agent has everything needed to choose correctly.

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 safety profile is known. The description goes beyond that by disclosing the blast radius (recipient rows deleted regardless of status), the irreversibility boundary (sent messages are not recalled), and the permission/feature gate.

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 its destructive scope, then the alternative, then the access gates. No filler or redundant 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?

No output schema exists, but for a delete primitive with one documented parameter that is not a gap. All decision-relevant context — scope of deletion, irreversibility, alternative tool, admin and feature requirements — is present.

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

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

There is a single required parameter 'id' and schema description coverage is 100%, so the schema already carries the full parameter semantics. The description adds no format, source, or discovery guidance for the ID, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a campaign') and immediately scopes it further by naming what else is removed ('its recipient rows, in any status'). It also distinguishes itself from the nearest sibling by pointing to cancel_whatsapp_campaign for the non-destructive path.

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

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

Gives an explicit when-to-use-this vs when-to-use-alternative rule: delete for permanent removal, cancel to stop a campaign while keeping delivery history. Adds hard preconditions ('Administrators only', 'Requires feature: whatsapp_campaigns') that gate whether the agent should attempt the call at all.

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 safety profile is covered externally. The description adds genuinely new behavioral context: only drafts are deletable and deprecation is the non-destructive path that preserves history and answers. It stops short of stating irreversibility or what happens to an in-flight/published flow rejected by this call, so it falls just short of a 5.

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

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

Two sentences, zero filler. The operation is front-loaded and the routing constraint follows immediately, with the alternative tool named in the same breath.

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

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

No output schema exists, but a delete operation needs little return documentation, and the annotations already carry the destruction/idempotency semantics. The description covers the one real ambiguity (draft vs. published). It could mention failure behavior when a published flow_id is passed, which keeps it from a 5.

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

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

Schema description coverage is 0% and the single parameter (flow_id) is never mentioned in the description. The name is largely self-explanatory, but the description does nothing to compensate for the missing schema documentation or to say where a valid flow_id comes from (e.g., list_whatsapp_flows).

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 ("Delete a WhatsApp Flow draft") plus an explicit scope restriction (drafts only), which cleanly separates it from the sibling delete_* tools and from deprecate_whatsapp_flow. An agent can distinguish this tool from every sibling 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?

Explicitly names the condition selecting this tool (drafts) and the alternative for the other case ("a published flow is retired with deprecate_whatsapp_flow instead"), including why the alternative exists ("keeps its history and answers"). This is textbook when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial behavioral context beyond them: what persists after the call (versions and collected answers), that the action is irreversible, and that a replacement must be created as a new draft. This is exactly the kind of consequence disclosure a mutation tool needs.

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

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

Two sentences, zero filler, with the core action and its consequence front-loaded. Every clause earns its place.

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

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

For a low-complexity, single-parameter mutation with rich annotations and no output schema, the description gives enough to call it correctly: precondition, irreversibility, and retained data. It could be slightly stronger by pointing to the delete counterpart for cases where removal (not deprecation) is intended.

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 the single flow_id parameter, so the burden falls on the description. It adds one meaningful constraint ('Only a published flow can be deprecated') but never explains the identifier's format or where to obtain it, so compensation for the coverage gap is only partial.

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

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

States a specific verb and resource ('Deprecate a published WhatsApp Flow') and immediately defines the effect. It implicitly distinguishes itself from the sibling delete_whatsapp_flow by noting that versions and existing customer answers are retained, so an agent can tell the two apart without opening either schema.

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

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

Provides a clear precondition ('Only a published flow can be deprecated') and the irreversibility outcome. It stops short of naming the alternative action (delete_whatsapp_flow) or the exact scenario that should select deprecation over deletion, so it is not a full when/when-not routing statement.

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

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

Annotations only flag destructiveHint=true generically; the description goes further by bounding the blast radius ('Messenger keeps working, and leads already received are kept') and stating the auth/feature prerequisites. This tells the agent exactly what is and is not destroyed, which is the highest-value disclosure for a destructive operation.

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

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

Four short sentences with zero filler, front-loaded with the action, then the scope of the change, then the prerequisites. Every sentence carries information an agent needs.

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

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

For a one-parameter destructive mutation with annotations and no output schema, the definition covers purpose, effect scope, and prerequisites adequately. The only omission is how to reverse the action (re-enabling via the sibling tool), which would round it out.

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

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

Schema description coverage is 100% and the single `id` parameter is already documented as 'ID of the Facebook Page channel (the `id` from the Pages list).' The description adds no syntax, format, or sourcing detail beyond that, so the schema does the heavy lifting and 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 and resource ('Disable Lead Ads on a Page') and immediately narrows scope ('Unsubscribes the Page from Meta's lead notifications'). It contrasts cleanly with the sibling enable_facebook_page_leads without needing the schema opened.

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 supplies the conditions that matter for choosing this tool: 'Administrators only' and 'Requires feature: facebook_marketing.' However, it never explicitly points to the enable_facebook_page_leads sibling as the inverse operation, so the when-not-to-use routing is left to inference.

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

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

Annotations cover the safety profile (destructive, non-idempotent, closed-world), and the description goes well beyond them: it discloses the permission precheck, the subscription side effect, a background sync start, and the exact success condition ('Leads are only marked enabled once Meta has accepted the subscription'). This is meaningful behavioral context an agent would otherwise have to guess.

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 purpose, then adds behavior and constraints; every clause carries information (permissions, subscription, sync, success condition, admin-only, feature gate). Slightly dense but 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 side-effecting mutation with no output schema, the description adequately covers prerequisites, side effects, and the completion condition. It does not describe what the caller observes after enabling (e.g., sync timing or return payload), leaving a minor gap.

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

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

Only one parameter with 100% schema description coverage ('ID of the Facebook Page channel'), so the schema already carries the meaning. The description adds no additional format or sourcing detail beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb ('Enable') and resource ('Lead Ads on a Page'), and its inverse sibling disable_facebook_page_leads makes the scope unambiguous without opening either schema. The description goes on to enumerate the concrete sub-operations (permission check, subscription, background sync).

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

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

Clear prerequisites are given ('Administrators only', requires feature facebook_marketing) plus the operational context of which permissions must be present. It stops short of explicitly naming alternatives (e.g., disable_facebook_page_leads or sync_facebook_lead_forms) or stating when-not-to-use.

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 and destructiveHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the actions run in the background, execute as the requesting person (impersonation/auth semantics), and the response returns before completion (async fire-and-forget). That async and identity behavior is exactly what the annotations cannot convey.

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

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

Three short sentences, front-loaded with the core action, and each sentence adds a distinct fact (action, background/identity, async return). The opening 'Run a macro.' is mildly redundant with the following sentence but the rest earns its place.

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

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

For a two-parameter mutation tool with full schema coverage, complete annotations, and no output schema, the description supplies the important missing pieces: asynchronous behavior and acting-as-the-requester semantics. It does not detail what the macro actions may alter, but the destructive annotation covers the risk signal.

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

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

Schema description coverage is 100%, so both macro_id and conversation_ids are already documented in the schema, making 3 the baseline. The description's phrase 'on the conversations named' confirms the target but adds no format, ordering, or validation detail beyond the schema.

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

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

The description states a specific verb+resource ('Run a macro') and expands to what running entails: executing a macro's actions against named conversations. This clearly separates it from create_macro, update_macro, delete_macro, and list_macros, though it never names those siblings 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?

There is no guidance on when to choose execute_macro versus the other macro tools, nor any prerequisites or exclusions. The only contextual hint is that it targets conversations already identified by the caller, which is implied rather than stated as usage guidance.

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

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

Adds substantial context beyond the annotations: the result is a DRAFT, no consent is requested, no call is placed, and the tool errors when there is nobody to follow up. It also defines the exact recipient selection rule. Note the mild tension with destructiveHint=true, which reads more severe than a non-calling draft creation, but nothing is actually contradicted.

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

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

Two dense sentences with the outcome, the recipient rule, the safety profile, and the failure condition, all front-loaded. Nothing repeats the schema or 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?

For a one-parameter mutation with no output schema, the description covers what is produced, what is not done, and when it fails. Only gap is what the call returns (presumably the new draft campaign), which would help since no output schema exists.

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

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

Schema coverage is 100% and the single parameter already points to list_voice_campaigns for the id, so the schema carries the load. The description adds no format, range, or constraint detail about campaign_id; 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?

Specific verb and resource: it creates a new DRAFT campaign carrying over configuration plus only the unreached contacts, and it enumerates exactly which contact states qualify. That distinguishes it in substance from clone_voice_campaign and create_voice_campaign, though it never names those siblings 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?

"launch it when ready" makes clear this tool only stages work and that launch_voice_campaign is the next step, and "Refused when there is nobody to follow up" states a precondition. It stops short of saying when to prefer this over clone_voice_campaign or create_voice_campaign, so the agent must infer the alternative.

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, non-destructive, and closed-world, so the safety profile is fully covered structurally. The description adds the returned field inventory, which is modest extra context but says nothing about permissions, account ambiguity, or error behavior beyond that.

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

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

One tight sentence with the resource and payload front-loaded and zero filler. It is arguably slightly long as an enumeration, but every element listed is meaningful information about 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 no output schema, the description usefully compensates by naming the fields returned (name, locale, domain, support email, status, features), so an agent knows what it gets back. It omits the `id` field that the schema enum permits and gives no pagination or shape detail, but for a parameterless read it is close to complete.

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

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

Schema description coverage is 100% and the single `fields` parameter is documented with a full enum, so the schema carries the load. The description's field list loosely mirrors a subset of that enum but adds no syntax, default, or omission semantics (e.g. what happens when `fields` is omitted).

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 (Get) and resource (account summary) and enumerates the fields returned, which lets an agent distinguish it from other get_* tools like get_details_of_a_single_account_agent_bot or get_agent_report. It stops short of explicitly naming a sibling it replaces, but the scope is clear.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives despite a large sibling set containing many account-level getters. The agent must infer that this is the account-wide settings read rather than an agent, inbox, or team read.

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 safety profile is covered. The description adds value beyond them by disclosing the return shape (one row per agent id) and the units of the time fields, plus the workflow dependency on list_agents for naming.

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 resource and window, then the metric list and keying/naming detail. No filler and nothing repeated from the 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?

With no output schema, the description responsibly names the returned metrics, their units, and the row key, and the parameters are fully covered by the schema. It omits edge cases such as whether agents with no conversations appear as zero rows, which keeps it just short of fully complete.

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

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

Schema description coverage is 100%; the days and fields parameters are fully documented in the schema, including the 'today included' counting rule and the default of 30. The description contributes only the N-days framing and does not restate the field enum or default, so 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+resource with scope: per-agent performance over the last N days, enumerating the exact metrics (conversations handled, avg resolution, first response, reply times). The 'per-agent' framing plus the 'rows are keyed by agent id' note separates it from team/conversation/sentiment report siblings without needing to name them.

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

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

The time window ('last N days') and the per-agent granularity give clear context for when this report applies, and it routes the agent to list_agents to resolve agent ids. It stops short of explicit exclusions (e.g., 'for team-level rollups use get_team_report'), so it is clear context rather than full when/when-not guidance.

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

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

Annotations already carry readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real value beyond that: it promises the full content is returned (not a summary) and directs the agent to 'quote what you found', which reduces paraphrasing/hallucination on a read.

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

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

Two short sentences, zero waste, with the identity of the tool front-loaded and the workflow instruction second. Nothing can be cut without losing meaning.

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

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

No output schema exists, but the description covers the return by stating the article comes with its full content. For a simple three-parameter getter with annotations supplying the safety profile, that is nearly sufficient; a note on the fields selector's effect on returned content would close the 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 67%, with portal_slug documented as 'as returned by list_portals'. The description contributes nothing about article_id or the optional fields selector, so the schema does all the parameter work—baseline 3.

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

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

States a specific verb and resource: 'Get one help center article with its full content.' The 'one ... full content' phrasing separates it from list_articles and from the KB-document siblings, 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.