Chatway Live Chat

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

The annotations already declare destructiveHint=true, idempotentHint=false, openWorldHint=false, so the safety profile is carried by structured data. The description adds useful context (a field is created when missing) but never warns that setting a value on an existing field overwrites it, which is exactly what a destructiveHint=true mutation tool should 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 short sentences, with the primary action front-loaded, then the entry-condition alternative, then the discovery tool. No sentence is redundant.

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

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

For a 3-required-parameter mutation with a full output schema and safety annotations, the description covers what to do, when to pick a sibling, and how to find field names. The only real gap is the silent-overwrite behavior on an existing field, which matters given destructiveHint=true.

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 descriptions already document the 100-character name limit, 1,000-character value limit, and how to obtain the visitor UUID. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Create a custom field ... and set its value') on a named target ('Chatway visitor/contact'), and it explicitly distinguishes itself from the two closest siblings, update-custom-data and list-custom-fields.

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 both alternatives and the exact condition that selects each: use update-custom-data when the field already exists, use list-custom-fields to discover existing field names. This leaves nothing to be inferred.

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

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

Annotations already declare non-read-only and non-destructive; the description adds the key behavioral fact that the note is visible to authorized teammates and never sent to the customer. It does not mention that repeated calls create duplicate notes despite idempotentHint=false, which is a minor remaining gap.

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

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

Two sentences, zero waste, with the audience/visibility constraint front-loaded before the alternative-tool routing.

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

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

Output schema exists so return values need no explanation, and the description covers purpose, audience, and routing. Only the duplicate-on-repeat behavior is left unstated for a non-idempotent write tool.

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

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

Schema coverage is 100% and both parameters are documented in-schema, including the 10,000 character limit and UUID format. The description only reiterates that content is teammate-visible, adding little syntax or format 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?

States a specific verb and resource ('Add a private internal note to a Chatway conversation') with the scope qualifier 'private internal' that immediately separates it from public messaging.

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?

Names the alternative sibling explicitly ('Use `send-message` instead when the customer should see the text') and gives the exact condition that selects it, so no inference is needed.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=false, so the risk profile is covered. The description adds genuinely new context: a tag may be auto-created if it doesn't exist, which is a meaningful side effect. However, it never acknowledges the destructive nature surfaced by the annotation, nor mentions permissions, rate limits, or what happens to an existing tag's color beyond the schema.

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

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

Three short sentences, front-loaded with the core action, then sequencing guidance. The hedge 'If supported by Chatway, the tag may be created' is a bit vague but does carry real information about conditional behavior, so it 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 an output schema present, return values needn't be explained, and all three parameters are documented. The remaining gap is that the destructive hint in annotations is never contextualized—an agent gets no sense of reversibility beyond the remove-tag pointer.

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

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

Schema description coverage is 100%, so all three parameters (name, color, conversation_id) are already fully documented, including reuse and color-override behavior. The description adds no syntax, format, or constraint detail beyond the schema, so baseline 3 applies.

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

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

Specific verb+resource: 'Attach a named tag to the visitor/contact associated with a Chatway conversation.' It clearly distinguishes itself from sibling tools like remove-tag, list-tags, and the custom-data tools, which operate on different objects.

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 prescribes the flow: call `list-tags` first to reuse an existing name, and use `remove-tag` to undo. Both the alternative and the condition selecting it are named, leaving nothing to inference.

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

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

Beyond the annotations it discloses three non-obvious behaviors: no-ops for conversations already in the requested state, a confirmation-token gate for multi-conversation calls versus immediate execution for a single conversation, and name/email resolution with an ambiguity fallback. It does not say whether the assigned agent is notified, what happens if an agent is already assigned to some of the listed conversations, or why the tool is marked non-idempotent despite the no-op guarantee — a mild tension worth noting, though not a 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?

Four sentences, front-loaded with the action, then identity resolution, then the no-op rule, then the confirmation/alternative rules. No sentence is redundant with the title, schema, or annotations, and nothing is buried.

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

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

With a full input schema, an output schema, and destructive/idempotency annotations already present, the description covers the risky parts an agent must know: the confirmation challenge, the batching limit context, and the ambiguity fallback. It stops short of describing permission requirements or side effects on the affected agents, which is the main remaining gap for a destructive mutation.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds value by explaining that agent identity can be supplied as UUID or as a name/email query (with an ambiguity escape hatch) and by instructing the caller to batch all conversation UUIDs into one call rather than looping. The confirmation_token flow is also framed in terms of the call sequence, not just its type.

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

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

The first sentence gives a specific verb pair (assign/unassign), the resource (agent on Chatway conversations), and the cardinality (one or more). It is immediately distinguishable from siblings like handoff-to-human, resolve-conversation, and list-agents, which is reinforced by the explicit routing note for list-agents.

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 both branches of use (default assign vs. `unassign: true`), the exact condition that should route the agent elsewhere ("Use `list-agents` only when an `agent_query` match is ambiguous"), and the multi-conversation confirmation workflow. The only unstated alternative would be handoff-to-human, but the assign/unassign framing already separates these.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the useful scoping detail that the check is about the current MCP session and is a diagnostic fallback, which is context beyond the annotations.

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

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

Two short sentences, purpose first and trigger second, 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?

An output schema exists, so return values need no explanation, and with no parameters and full annotation coverage the description supplies everything an agent needs to decide to call 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 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+resource: checks whether the current MCP session has an active Chatway connection. This clearly separates it from the inbox-action siblings, though it doesn't explicitly name them as 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?

Gives a concrete trigger: use when Chatway inbox tools are unavailable or auth may have expired. That is clear context, but it stops short of explicit exclusions (e.g. don't poll it routinely).

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 genuinely new scope information — that the full message history is NOT returned, and that only 'accessible' conversations can be fetched (an implicit permission boundary). Missing only details like error behavior for inaccessible UUIDs.

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: what it returns, what it excludes, and how to choose between it and the sibling. The scope limitation and the alternative are both front-loaded 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 one-parameter read tool with rich annotations and an output schema, nothing material is missing: payload contents are summarized, the message-history exclusion is called out, and the sibling routing is specified. Return-value detail is correctly left to the 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?

Single required parameter with 100% schema description coverage ('The UUID of the conversation to retrieve'). The description's 'by UUID' restates the schema rather than adding format or sourcing guidance, so the schema does the work here; 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 ('Retrieve') and resource ('one accessible Chatway conversation by UUID') and enumerates what comes back: status, contact, channel, assigned agents. It is unmistakable against siblings like list-conversations or list-conversation-messages.

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

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

Explicitly conditions usage: use this when you already have a conversation UUID, and names the alternative (`list-conversation-messages`) for reading messages. That is a direct when/when-not routing rule an agent can act on.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, and the description builds on that by defining the division of labor: the tool returns code, the coding agent installs it with its own tools, and the agent must relay placement options to the user. This is real behavioral context beyond the annotations, though it says nothing about the size or format of the returned snippet.

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 lead sentence is front-loaded and effective, but the head/body placement instruction is stated twice (once as guidance, again in the mandatory user-facing disclosure), and the platform list (Shopify, Wix, WordPress) is likewise repeated verbatim, padding the definition.

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

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

For a zero-parameter read tool with an output schema and full annotation coverage, the description supplies the essential operational context: check first, install once, where to place the snippet, platform alternatives, and who performs the install. An output schema exists so return-value details are rightly omitted.

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

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

With zero parameters the baseline is 4, and the description usefully explains why there are none: the installation ID is account-based so no widget selection is needed. That preempts an agent wondering whether it must supply an account or widget 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?

"Get the JavaScript snippet that installs Chatway for the connected account" is a specific verb plus resource with clear scope. The follow-up clarifies the account-based installation ID so no widget selection is required, and the ordering instruction (check existing installation first) implicitly separates this from get-installation-status.

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 strong when-to-use guidance: check for an existing installation before adding script_html, install only once, place in a shared layout. It also names alternatives (Chatway native app or plugin on Shopify, Wix, WordPress), though it never states an explicit case where this tool should not be called.

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

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

Beyond the readOnly/idempotent/openWorld annotations, it discloses the important caveat that script_detected does not guarantee the widget is enabled or visible, and that unverified_spa may load the script dynamically. This is meaningful behavioral context annotations cannot convey; only minor gaps remain (no mention of authentication or rate limits).

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

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

The description is front-loaded with the core action, then maps statuses to interpretations, then gives fallback verification steps. Each sentence carries information, though the remediation passage makes it slightly longer than strictly necessary.

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

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

With an output schema present, the description need not enumerate return fields, and it wisely spends its words on interpreting status values instead. For a one-parameter read-only check, an agent has everything needed to call it and act on the result.

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

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

Schema description coverage is 100% and the single domain parameter is already documented as accepting a bare domain or a full URL. The description adds no additional parameter-level meaning, 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 states a specific verb and resource ('check for evidence that Chatway is installed on a website for the connected account') and defines what each resulting status means, so an agent knows precisely what question this tool answers. It is clearly separable from the sibling get-installation-code, which retrieves code rather than verifying installation.

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

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

It gives concrete procedural guidance for ambiguous outcomes: if browser access is available, open the site and verify; otherwise ask the user to start a test chat and re-check. What is missing is an explicit pointer to sibling alternatives such as get-installation-code when the agent actually needs the snippet rather than a status check.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds that only profile data visible to the authenticated connection is returned, which is permission-scoping context not present in the annotations. Return shape is covered by the output schema, so no further detail is 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?

Two sentences, no filler. The identification statement comes first, the routing guidance second, and the UUID prerequisite is surfaced before the alternative is mentioned.

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?

One required parameter, full schema coverage, complete annotations, and an output schema that handles the return values. The description covers the only remaining decisions an agent faces: whether the UUID is in hand and where to get it otherwise.

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

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

Schema coverage is 100% and the schema's visitor_id description already supplies both examples (contact.id and id from search-contacts). The description restates the same example rather than adding format or validation detail beyond the schema, so this is the baseline case.

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 ('Retrieve') and resource ('one Chatway visitor/contact profile'), scoped by visitor UUID. It is clearly distinguished from search-contacts, the sibling that resolves a contact by other means.

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

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

Explicitly says to use this when the UUID is already known, gives a concrete source for that UUID (contact.id from get-conversation), and names the alternative (search-contacts) for the opposite case.

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

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

Adds substantive behavior beyond the annotations: it records a request but does not guarantee a human has joined or replied, it errors when no AI assistant is assigned, and it constrains follow-up messaging. None of this is derivable from readOnlyHint=false / destructiveHint=false / idempotentHint=false.

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 precondition, and every sentence carries usable information. Slightly repetitive in restating 'Chatway AI assistant' and could tighten the clause about erroring into a shorter form.

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 one-parameter mutation tool with an output schema and rich annotations; the description covers the precondition, failure mode, non-guarantee, and follow-up restriction. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and documents conversation_id as a UUID, so the schema carries the type burden. The description still adds meaning by constraining which conversation is valid (one currently handled by an AI assistant) and what happens if that constraint is violated.

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: 'Request human-agent handoff for a Chatway conversation that is currently handled by a Chatway AI assistant.' The precondition (AI assistant must be assigned) distinguishes it from the similarly named assign-conversation and resolve-conversation siblings.

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

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

Gives the trigger condition ('when the customer asks for a person or the request cannot be handled with the available tools'), names the fallback alternatives when the precondition fails ('assign a teammate with assign-conversation or add a private note instead'), and states a post-condition rule ('after handoff, do not reply with send-message').

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, and the description adds the lookup-resolution purpose that explains why this read exists. Minor gap: pagination/truncation behavior from the limit default isn't described, but that is largely covered by the schema.

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

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

Two sentences, no filler; the purpose and the prerequisite for assignment are front-loaded, then the exclusion is stated. 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?

An output schema exists so return values need no explanation, annotations cover the safety profile, both params are documented, and the description supplies the one thing structured data can't: why and when to call this rather than the sibling. Nothing material is missing.

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

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

Schema description coverage is 100%, so both limit and query are fully documented in the schema itself. The description only restates that matching is by name or email, which is already in the query parameter description, so baseline 3 applies.

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

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

States a specific verb and resource ('List or search Chatway teammates by name or email') with the exact matching fields named. It also distinguishes itself from the sibling assign-conversation, so an agent can tell the two apart without inspecting schemas.

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

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

Given the explicit 'Use this to obtain an unambiguous agent UUID before assigning conversations' plus a clear when-not clause mentioning the assign-conversation agent_query alternative, an agent knows exactly when to route here versus assigning directly by 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 readOnly, idempotent, non-destructive and closed-world. The description adds useful traits beyond that: fixed ordering, pagination support, and that system/internal messages are excluded unless opted in.

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

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

Three sentences, each carrying distinct information: scope and ordering first, capability second, operational guidance third. 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?

Covers purpose, ordering, pagination and filtering, and an output schema plus read-only annotations handle return shape and safety. Only minor gaps remain, such as default page size, which the schema already supplies.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including the `next_before_sort_number` paging hint. The description's mention of pagination and optional message types largely restates that, adding little new 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 ('List messages'), scopes it to 'one accessible Chatway conversation', and adds the ordering ('newest first'). That is enough to separate it from get-conversation and list-conversations 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 an explicit usage cue ('Read the history before summarizing or replying') and tells the agent how to page backwards with `before_sort_number`. It does not name a sibling alternative or state exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds useful return context (conversation metadata plus a latest-message preview) that tells the agent what it gets back 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?

Three tight sentences, front-loaded with the core action and ordering, followed by return shape and sibling routing. 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 annotations covering safety, a complete input schema, and an output schema to explain return values, the description supplies everything an agent needs: scope, ordering, filtering, and sibling routing.

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 page, per_page, and the status enum are fully documented in the schema; baseline 3 applies. The description only restates that status filtering is optional, adding little beyond the schema.

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

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

States a specific verb and resource (list Chatway conversations) plus the ordering (newest first) and the optional resolved-status filter. It distinguishes itself from siblings by explicitly naming what list-conversation-messages and search-conversations are for.

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 alternatives with conditions: use list-conversation-messages to read full history, use search-conversations to find a specific conversation by subject/URL/contact instead of paging. When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered by structured fields. The description adds useful behavioral context beyond that: team-scoping and the fact that definitions (not values) are returned. It stops short of describing ordering or pagination, but an output schema exists to cover the return shape.

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

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

Three short sentences with no filler: scope first, the key exclusion second, and the workflow routing last. Every sentence carries distinct, actionable information and the most important constraint 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 zero-parameter, read-only list tool with full annotation coverage and an output schema, the description supplies exactly what structured fields cannot: what the data represents (definitions, not values) and how it fits into the add/update workflow. Nothing an agent needs to select or invoke this tool is missing.

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

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

The tool takes zero parameters, which sets the baseline at 4. The description correctly implies no filtering is required or possible and adds scope framing (authenticated team), consistent with an empty schema. There is no additional parameter nuance to 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?

The description names a specific verb and resource ('List the custom-field definitions') and scopes it to the authenticated Chatway team. It explicitly distinguishes itself from a value-returning operation by stating it does not return field values for a particular visitor, so an agent won't confuse it with per-visitor data retrieval.

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

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

It gives an explicit when-to-use rule: call this before `add-custom-data` or `update-custom-data` to reuse existing field names. It also carves out the negative case ('does not return field values'), which prevents misuse by agents looking for visitor data. The sibling alternatives are named directly.

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 covered. The description adds the meaningful constraint that results are limited to the authenticated team's tags, and notes the returned content (names, colors) — useful operational context beyond the annotations.

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

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

Two sentences, zero filler. What the tool returns is front-loaded and the workflow routing to `add-tag` follows immediately.

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 parameters, rich annotations, and an output schema that documents the return shape, the description needs only to say what is listed and when to call it — both are present. Nothing an agent needs in order to invoke this correctly is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to clarify. The schema is empty and consistent with the description's no-argument framing.

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

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

States a specific verb and resource ('List the tags') plus the scope ('available to the authenticated Chatway team') and the returned fields ('names and colors'). An agent can distinguish this from add-tag, remove-tag, and the custom-field list tools without inspecting 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 tells the agent to call this before `add-tag` so an existing tag name can be reused, naming the sibling and the ordering condition. It stops short of stating when NOT to call it (e.g., when a tag ID is already known), so it is clear but not exhaustive.

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 structurally. The description adds the useful scoping nuance that only the value is removed, not the field itself, but it never says whether the call fails or silently no-ops when the field is absent, nor whether removal is reversible — gaps that matter for 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?

Two tight sentences: the action and scope come first, the alternative routing second. No filler or restated title text.

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

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

An output schema exists and both parameters are fully documented, so the description does not need to explain return values. For a destructive two-parameter mutation, the only missing piece is the error/no-op behavior when the named field is not present on the visitor.

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

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

Schema description coverage is 100%, including a concrete hint that visitor_id comes from `get-conversation` or `search-contacts`. The description adds no further semantics about the parameters, so the baseline 3 applies with the schema doing all the work.

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

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

States a specific verb (remove) and a precisely scoped resource (a named custom-field value on a Chatway visitor/contact). The phrasing 'custom-field value' distinguishes it from deleting a field definition, and the tool is clearly differentiable from add-custom-data and update-custom-data.

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

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

Explicitly routes the agent to `update-custom-data` when the value should change rather than be removed, which is the primary ambiguity for this operation. It does not address the related case of a value that does not yet exist, where `add-custom-data` would be the correct sibling, so one meaningful branch is left unstated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=false, so the risk profile is covered structurally. The description adds useful scoping (the tag is removed from the conversation's visitor/contact), but says nothing about what happens if the named tag does not exist (error vs. silent no-op).

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 action is front-loaded before the prerequisite hint. Nothing could be removed without losing information.

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

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

With only two required parameters, full schema coverage, an output schema, and annotations covering destructiveness, the description is nearly sufficient. The only meaningful gap is the behavior on a non-existent tag name, which matters for a destructive mutation.

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, establishing a baseline of 3. The description's pointer to `list-tags` for the exact tag name adds a small amount of practical meaning about the `name` parameter's expected precision.

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

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

The description states a specific verb and resource ('Remove a named tag') and scopes it precisely to 'the visitor/contact associated with a Chatway conversation', which cleanly separates it from the add-tag sibling. 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?

It gives a concrete prerequisite: use `list-tags` to check the exact tag name before removing. That is actionable routing guidance, but there is no explicit exclusion such as what to do when the tag is absent from the contact.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, but the description adds genuinely new behavior beyond them: the two-tier confirmation model (multi-conversation calls require user confirmation, single calls do not) and the batching expectation. It stops short of describing side effects such as whether resolution notifies participants or closes the thread, which would be the remaining useful detail.

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 followed by the batching and confirmation rules, with no filler. Slightly dense in the middle sentence where the confirmation rule and immediacy rule are compressed together.

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

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

An output schema exists and the schema fully documents both parameters, so the description's job is mainly the confirmation workflow and it covers that well. It does not say what happens when a confirmation_token is missing, expired or invalid, leaving the failure path unaddressed for a destructive operation.

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

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

Schema description coverage is 100% and the schema already documents both the 1-30 UUID range and the purpose of confirmation_token. The description reinforces the batching intent for conversation_ids but adds no syntax or format detail beyond what the schema states, so it sits at the 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 ("Mark ... conversations as resolved") and names the sibling that does the opposite ("Use `unresolve-conversation` to reopen conversations"), so an agent can distinguish the pair without opening either schema.

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

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

Gives explicit operational guidance: batch all target UUIDs into one call, expect a confirmation challenge when resolving more than one conversation, and single conversations resolve immediately. It also names the alternative tool for the inverse operation, covering both when-to-use and when-to-use-something-else.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds useful scope information—result set is limited to 'accessible' contacts and excludes message bodies—but says nothing about ordering, pagination, or match semantics (exact vs partial), which annotations can't 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?

Two short sentences with zero filler: capability plus scope first, the alternative routing second. 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?

With an output schema present and rich annotations, the description need only cover scope and routing, which it does. The one gap is match behavior—an agent can't tell whether the query is substring, prefix, or fuzzy—which matters for a search tool.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the limit range of 1 to 50. The description's restatement that query matches name, email, or phone duplicates the schema rather than adding format or matching-behavior detail. 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 (search) and resource (contacts) plus the three searchable attributes, and explicitly bounds scope with 'does not search conversation messages'. That scope line separates it cleanly from the sibling search-conversations.

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?

Names an explicit alternative and the condition that selects it ('use get-visitor instead when you already have the contact's UUID'). It does not explicitly route to search-conversations for the message case, though the negative scoping sentence implies that handoff.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it searches only accessible conversations and does not search message bodies, directing the agent to use returned IDs for message retrieval. It does not add auth/rate-limit details, but those are less critical here.

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

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

Three sentences, front-loaded with the core search behavior, followed by the key limitation and the relevant alternative. Every sentence adds information an agent needs, with no redundant restatement of the tool name.

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

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

The tool is a straightforward search endpoint with an output schema, full input schema coverage, and annotations covering safety. The description supplies the important missing behavioral nuance: it does not search message bodies, and `list-conversations` is the browsing alternative. Nothing material 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 100%, so both parameters are already documented in the input schema. The description adds minor precision by naming the searchable fields as email subject, origin URL, and contact name/email, but it does not explain `limit` beyond what the schema already provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: search accessible Chatway conversations. It then lists searchable fields (email subject, origin URL, contact name/email) and explicitly distinguishes the scope from message-body search, so an agent can identify what this tool 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?

It gives clear usage guidance: search conversations by subject/URL/contact, do not use it for message bodies, use returned conversation IDs to retrieve messages, and use `list-conversations` for browsing or status filtering. These are explicit alternatives and exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds a useful grounding constraint (use returned content, don't invent unsupported information) but says nothing about result quality, empty-result behavior, or match semantics. The output schema covers return values.

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 resource and scope, then the usage rule. Slight overlap between 'use the returned content to answer or draft a response' and 'use it before drafting a reply with send-message' but nothing wasteful.

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

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

With an output schema present, rich annotations, and full schema coverage, the description only needs to convey purpose and usage, which it does. The one gap is search behavior (matching semantics, behavior on no matches), which would help an agent set expectations.

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

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

Schema description coverage is 100%, so both parameters (query, limit) are already documented in structured data; a 3 is the baseline. The description adds no meaning about how 'query' is matched (keyword vs. semantic) or what happens with an empty query, which would have been genuinely useful.

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 ('Search the authenticated team's Chatway knowledge-base questions and answers') with a clear scope qualifier (the authenticated team's own content). This is easily distinguished from the sibling search tools (search-contacts, search-conversations), which target different resources.

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

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

Gives an explicit trigger ('Use it before drafting a reply with send-message so answers match the team's own content') and names the sibling it pairs with. It lacks an explicit when-not case (e.g., don't use for conversation history — use list-conversation-messages instead), which keeps it from 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=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is known. The description adds genuinely new behavioral context: that the message is customer-visible, that it is an external side effect, and that it must not fire after a handoff. It does not discuss failure modes or acknowledgement behavior, but with rich annotations a 4 is warranted.

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

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

Three sentences, front-loaded with the action, then the risk, then the alternative. No filler or 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?

Mutation tool, but annotations carry the destructive/open-world profile, both params are fully documented, and an output schema exists so return values need not be explained. Nothing required for correct invocation is missing.

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

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

Schema description coverage is 100% and both parameters carry descriptions including the 10,000-character limit, so the schema does the heavy lifting. The description adds no additional meaning about content formatting or conversation_id semantics, which is the expected baseline-3 outcome.

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

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

States a specific verb and resource ('Send a customer-visible reply to a Chatway conversation') plus the acting identity ('as the authenticated agent'), and explicitly contrasts with the sibling add-note. An agent can distinguish it from list/add/update siblings 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 exclusions ('do not use it when the user only asks for a draft or after human handoff has been requested') and names the correct alternative ('Use `add-note` for internal comments'). This is exactly the when/when-not/alternative structure that earns 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 flag destructive=true and non-idempotent, but the description adds the non-obvious confirmation gate: multi-conversation calls require user approval while a single conversation 'is reopened immediately'. That asymmetry is real behavioral context an agent cannot infer from the schema alone. It does not describe what state the conversation returns to, a minor gap given the destructive hint.

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

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

Four short sentences, front-loaded with the action, then the batching rule, then the confirmation caveat, then the inverse tool. No filler 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?

With an output schema present, return values need no explanation, and the description covers action, batching, confirmation workflow, and the inverse tool. Only the post-reopen conversation state is left implicit.

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

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

Schema description coverage is 100%, including the 1-to-30 range and the confirmation_token challenge flow, so the schema does the heavy lifting. The description only reinforces that IDs should be batched into one call rather than adding syntax or format 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?

Specific verb and resource: 'Reopen one or more resolved Chatway conversations.' It names the exact target state (resolved) and the exact action (reopen), making it immediately distinguishable from resolve-conversation among 20+ siblings.

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

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

Explicitly routes the agent to the inverse tool ('Use resolve-conversation to close them again') and gives a batching rule ('Send all target conversation UUIDs in one call'), so the agent knows both the alternative and the preferred calling pattern.

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=false, and readOnlyHint=false, so the safety profile is covered structurally. The description reinforces this with 'replace the value' and the existing-field prerequisite, but it omits failure behavior (for example, what happens if the field is absent) and any permission requirements. That is useful but modest added context over the annotations.

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

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

Three short sentences, the mutation action is front-loaded, and each subsequent sentence adds routing value with no filler. Nothing is redundant with the title or schema.

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

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

For a three-parameter mutation with full schema coverage, annotations declaring destructiveness, and an output schema that covers return values, the description is nearly complete. The only gap is failure/error behavior when the named field does not exist, which the description hints at by redirecting to add-custom-data.

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 all three parameters documented, including length limits and the UUID source for visitor_id. The description adds only the semantic that the field must already exist; with the schema doing the heavy lifting, 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 states a specific verb and resource ('Replace the value of an existing custom field on a Chatway visitor/contact') and scopes it to existing fields only. It clearly distinguishes this tool from add-custom-data (create) and list-custom-fields (discovery), so an agent can select it without inspecting the schema.

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

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

It gives explicit routing rules: use add-custom-data when the field does not exist, and use list-custom-fields to verify the exact field name first. Both alternatives are named with the condition that selects them, leaving nothing to inference.

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