Chatway Live Chat

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/safety profile is covered. The description adds the useful create-if-necessary side effect, but does not say whether an existing value on the contact is overwritten, what errors occur, or any auth/rate-limit constraints.

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, action front-loaded, with the alternative routing in the second clause. No padding 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?

For a flat three-parameter tool with no output schema and annotations covering the safety profile, the description is nearly sufficient. The remaining gap is the undocumented required parameters and unstated overwrite behavior, which is minor given the tool's low 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% across three required parameters, so the description must compensate and largely does not. It implies a field name and a value, but never explains name, value, or visitor_id semantics (formats, whether the field must pre-exist, what identifier visitor_id expects).

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 compound action (create field if needed, then set its value) on a named resource (custom field on a Chatway visitor/contact). It explicitly names the sibling it is not (update-custom-data), so an agent can distinguish the two without opening either schema.

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

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

Gives a clear routing rule: use update-custom-data when the field already exists, implying this tool is for when it does not. That covers the primary add-vs-update decision, but other siblings (remove-custom-data, view-custom-fields) and any explicit "when not to use" case are left unaddressed.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the mutation profile is covered. The description adds genuinely new context: the note is private, visible only to authorized teammates, and never delivered to the customer — audience/visibility semantics annotations cannot express.

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

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

Two short sentences, no redundancy, with the essential visibility constraint front-loaded in the first sentence.

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

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

For a two-parameter mutation with a clear annotation profile and no output schema, the description covers what the tool does and who sees the result. It could note the return value or permission requirements, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 50%: 'content' is documented but 'conversation_id' is not, and the description adds no explanation of either parameter beyond saying the note attaches to a conversation. Baseline 3 is appropriate since the description neither compensates for the gap nor misleads.

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') and immediately clarifies the audience, which cleanly separates it from the send-message sibling that reaches the customer.

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

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

The phrase 'not sent to the customer' implies the appropriate use case (internal-only communication) but never states when to choose this over send-message or add-tag explicitly. Usage is inferable rather than directed.

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 write/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds useful behavior beyond that - it attaches to the contact tied to the conversation and may auto-create the tag if absent - but this is hedged with 'If supported by Chatway', leaving the side effect ambiguous. No auth or failure behavior is given.

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 core action and no filler. The only slack is the conditional hedge about tag creation, which weakens precision more than it adds length.

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 mutation with annotations covering safety and no output schema, the description is mostly adequate, but the undocumented color parameter and the vague auto-creation behavior leave real gaps an agent would want covered.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it never explains the three parameters. 'name' and 'conversation_id' are loosely implied, but 'color' is completely 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?

The description names a specific verb (attach) and resource (named tag) and scopes it to the visitor/contact on a Chatway conversation, so the operation is unambiguous. It does not explicitly differentiate itself from siblings like remove-tag or view-tags, which caps it below 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 when-to-use guidance and no mention of alternatives such as remove-tag or view-tags, nor any condition that selects this tool over them. Usage is only implicit from the operation 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 declare the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real behavioral value: the confirmation requirement before assignment and the confirmation_token flow. It does not spell out what unassignment does to existing assignments, but adds meaningful context beyond 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?

A single front-loaded sentence carrying action, agent resolution, batch guidance, and the confirmation requirement with no wasted wording.

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

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

For a mutation tool with a 4-param schema, no output schema, and safety annotations already covering the destructive profile, the description supplies the key missing operational context: confirmation flow and batch behavior. Only the effect of unassignment on existing state is left 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 100%, so agent_id/agent_query/confirmation_token semantics are fully documented in the schema. The description re-echoes the UUID-or-query alternative and adds a batch hint ('one call'), but otherwise defers to the schema, matching the baseline 3.

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

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

States a specific verb pair (assign/unassign) against a specific resource (agent on Chatway conversations) with explicit scope (one or more). An agent immediately knows the action and target 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?

Provides procedural guidance (resolve agent by UUID or name/email, batch all conversation UUIDs, confirm before changing), but never states when to use this over a sibling like handoff-to-human, nor any when-not conditions. Usage is implied rather than explicitly scoped.

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 fully covered by structured data. The description adds that the check is scoped to the current MCP session and frames the likely failure mode (auth expiry), which is useful context. It says nothing about latency, caching, or what state is actually probed, so it clears the lowered bar but doesn't exceed it.

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 core purpose is front-loaded in sentence one and the routing guidance in sentence two. 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?

There is no output schema, so the description is the only place an agent could learn what the result looks like — but it never says whether a response is a boolean, a status string, or an error payload, nor what the agent should do when the check reports a dead connection. For a simple diagnostic this is a tolerable gap, but the return-value burden falls entirely on the description and is unmet.

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 by rule the baseline is 4 — there is nothing for the description to disambiguate in the schema. The description correctly implies the session is the implicit input rather than a passed argument, which is consistent with the empty 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 ('check') and a precise resource ('whether the current MCP session has an active Chatway connection'), which no sibling tool does — the rest of the siblings operate on conversations, contacts, tags, and messages. An agent can immediately distinguish this diagnostic tool from all 21 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 an explicit trigger condition: 'Use this when Chatway inbox tools are unavailable or authentication may have expired.' That is clear when-to-use guidance tied to observable symptoms. It stops short of a full 5 because it doesn't say when NOT to call it (e.g., avoid calling preemptively on every session start) or name a specific tool to try first.

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 safety is covered. The description still adds genuine behavioral value by disclosing that the full message history is NOT returned and that the conversation must be 'accessible' (a permission scoping signal), which prevents an agent from assuming a full-detail fetch.

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: the retrieval scope is front-loaded, and the negative constraint follows immediately. 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?

With no output schema, the description carries the return-value burden and does so adequately by naming the included fields and excluding message history. It stops short of describing shape or nesting, but for a single-parameter read tool this 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% for the single conversation_id parameter, so the schema does the work and baseline is 3. The description reinforces the UUID format but adds no new parameter-level 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 ('Retrieve one accessible Chatway conversation by UUID') and enumerates the returned field set (status, contact, channel, assigned agents). The explicit exclusion of message history distinguishes it from the sibling list-conversation-messages 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?

The 'by UUID' framing implies the usage condition (you already have an identifier) and the negative scoping hints at the message-history alternative. However, it never explicitly names when to prefer this over search-conversations or list-conversations, leaving routing 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, destructiveHint=false and openWorldHint=false, so the agent knows this is a safe closed-world read. The phrase 'including the profile data available to the authenticated connection' adds a bit of scope/auth context, but it is ambiguous and does not describe what is returned or what happens on a missing/unauthorized UUID.

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 resource, no filler. Slightly hampered by the trailing qualifier that reads as hedging rather than 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 single-param read tool with full annotation coverage and no output schema, the definition covers the essentials. However, it omits any description of the returned profile shape or error behavior, and with no output schema there is nothing else to fill that gap.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema as the visitor UUID. The description only restates that the lookup key is a visitor UUID, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Retrieve one Chatway visitor/contact profile by visitor UUID'), clearly distinguishable from search-contacts and list-* siblings. Lacks explicit sibling naming but the single-fetch semantics are 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?

No when-to-use guidance and no alternatives named. A vague clause about 'available to the authenticated connection' hints at scope but does not tell the agent when to pick this over search-contacts.

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 non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds genuinely useful behavioral context beyond that: the handoff is only recorded and 'does not guarantee that a human has joined or replied,' which tells the agent this is fire-and-forget rather than a confirmed escalation. It still omits auth/permission requirements or rate limits, 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?

Two tight sentences with zero waste. The core action is front-loaded, and the important caveat follows immediately rather than being 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?

For a single-parameter mutation with no output schema and no nested objects, the description covers purpose and the key behavioral caveat. It leaves minor gaps (what state the conversation enters afterward, required permissions) but nothing that would cause a misinvocation.

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 exists and schema description coverage is 0%, so the description technically must compensate, but it says nothing about conversation_id beyond the word 'conversation.' The parameter name is largely self-explanatory, keeping this at a minimum-viable 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 ('Request human-agent handoff') scoped to a Chatway conversation, which is enough for an agent to act on. It does not explicitly differentiate itself from the neighboring assign-conversation tool, which is the closest ambiguous sibling, so it falls short of a 5.

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

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

The description explains what the tool does but gives no when-to-use guidance, no trigger conditions for escalation, and no mention of the assign-conversation alternative. An agent must infer the escalation scenario 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds no behavioral detail beyond that — nothing about pagination, result ordering, or what happens when the query matches nothing, though the limit parameter implies paging.

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; the purpose is front-loaded and the usage hint 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?

For a two-parameter read-only list tool with no output schema, the description plus annotations give an agent everything needed to invoke it correctly. It would be marginally stronger with a note on result volume or the default page size.

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 (limit, query) are already fully documented in the schema. The description only restates the query filter as "by name or email" and adds no format or default information beyond what the schema provides; 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 ("List or search Chatway teammates") plus the scope of the filter (by name or email). It also implicitly distinguishes itself from conversation-oriented siblings by framing its output as the agent UUID needed by assign-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 gives a clear activation condition: use it to obtain an unambiguous agent UUID before assigning conversations. There are no explicit exclusions or named alternatives, but for a simple list tool the routing guidance is sufficient.

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 safety is covered. The description adds genuinely useful behavior beyond that: results are newest-first, pagination is supported, and system/internal message types are excluded unless explicitly opted in via flags.

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; the core action and ordering are front-loaded before the pagination and inclusion details. 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 read-only listing tool with no output schema and fully documented parameters, the description covers action, ordering, pagination, and content filtering. Only minor gaps remain, such as how the pagination cursor relates to the next page of results beyond what the schema states.

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 five parameters including defaults and the 1-100 limit range. The description's mentions of pagination and optional system/internal inclusion largely restate what the schema says, adding only framing rather than new syntax 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 specific verb and resource ('List messages from one accessible Chatway conversation') plus ordering ('newest first') and scope ('one accessible conversation'). It is clearly distinguishable from conversation-level siblings like list-conversations and get-conversation, though it does not name any 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?

Usage is implied by the scoping phrase 'one accessible conversation,' which tells the agent this is a per-conversation read. However there is no explicit when-to-use, no when-not, and no named alternative for related tasks such as fetching a single message or searching across conversations.

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 safety is covered. The description adds real value beyond that by disclosing return ordering and content (metadata plus a latest-message preview) and the 'accessible' scope limitation. It doesn't mention pagination behavior, which is a minor 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, front-loaded with the core action and scope, then the routing hint. Every clause carries information; nothing is redundant or padded.

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

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

With no output schema, the description usefully summarizes the return payload (metadata + latest-message preview). For a simple read-only list tool with fully documented parameters, this is nearly sufficient; only pagination semantics are unaddressed, though the schema covers them.

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 every parameter has a documented purpose with defaults, so the schema does the heavy lifting. The description only restates that unresolved/resolved filtering exists, adding no syntax or semantics beyond the enum 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?

States a specific verb (List) and resource (Chatway conversations), plus ordering (newest first) and optional filtering. It also explicitly distinguishes itself from list-conversation-messages, so an agent can route correctly without opening a schema.

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

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

Clearly says to use list-conversation-messages when full message history is needed, which is the most likely alternative an agent would confuse it with. It does not address when to prefer search-conversations over this list, so one sibling ambiguity remains.

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, so repeating 'this is destructive' adds nothing. However, 'requires user confirmation' is genuinely additive context that explains the confirmation_token field and the approval flow, lifting it above a pure restatement.

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 action and scope, with the safety note immediately after. 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?

No output schema exists, and the annotation covers the safety profile, but the description omits behavior on missing fields/visitors, error semantics, and the mismatch between 'requires user confirmation' and the schema marking confirmation_token as optional.

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 carries the burden; it maps 'named custom-field' to name and 'visitor/contact' to visitor_id, and hints at confirmation via 'requires user confirmation'. It still doesn't clarify that confirmation_token is optional in the schema or give any format guidance.

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: removing a named custom-field value from a Chatway visitor/contact. It is distinguishable from siblings like remove-tag and update-custom-data, though it does not explicitly name an alternative.

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 and by the note that confirmation is required, but there is no explicit when-to-use vs. update-custom-data (which could also clear a value), and no stated prerequisites such as required scopes.

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, and the description reinforces the destructive nature. It adds genuinely new context by stating that user confirmation is required, which explains the confirmation_token parameter and the mutation workflow beyond what the annotations convey.

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

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

Two compact sentences with zero padding, and the destructive warning is placed up front. Nothing redundant, though it could not be called richly 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 3-param mutation tool with no output schema and no schema descriptions, the definition covers the core action and the confirmation prerequisite. It omits what happens if the tag is absent, whether removal is reversible, and the exact role of confirmation_token, leaving real gaps.

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

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

Schema description coverage is 0%, so the description carries the burden. It implicitly clarifies 'name' (a named tag) and 'conversation_id' (the conversation the contact belongs to), covering two of three parameters, but says nothing about confirmation_token or expected formats.

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 ('Remove a named tag') and scopes it to the visitor/contact of a Chatway conversation, which distinguishes it from the sibling add-tag. It does not explicitly name the counterpart tool, but the removal semantics are unambiguous.

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

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

Usage is implied by the destructive nature and the 'requires user confirmation' gate, but there is no explicit when-to-use/when-not guidance or reference to alternatives such as add-tag or view-tags. An agent can infer intent, yet nothing directs it between siblings.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'This is destructive' largely restates structured data. It does add the two-step confirmation requirement, but that flow is also described in the confirmation_token schema field, so incremental value is modest.

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

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

Three short sentences with the action front-loaded, followed by the calling convention and the safety caveat. Nothing is wasted or 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?

For a mutation with no output schema, the description covers the action, batching, and the confirmation gate, while annotations carry the destructive profile. It stops short of noting that the change can be reversed via unresolve-conversation or what the call returns.

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 confirmation_token description, so both parameters are documented structurally. The description's only addition is that multiple UUIDs should be batched into one call, which the array type already implies. 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 ('Mark ... as resolved') and resource ('Chatway conversations'), with scope for one or many. It does not explicitly name the sibling unresolve-conversation, but the operation is unambiguous against the rest of the sibling 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?

'Send all target conversation UUIDs in one call' gives concrete batching guidance, and 'requires user confirmation' states a precondition for calling. No explicit exclusion or named alternative (e.g. unresolve-conversation) is given, keeping it short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the permission-scoping word 'accessible' and the negative search scope; it says nothing about result ordering, pagination beyond the schema's limit, or truncation 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, front-loaded with the action and scope, followed by the exclusion. No filler and nothing that could be cut without losing signal.

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 read-only search with no output schema, the description covers what is searched and what is not, which is the essential routing information. It stops short of describing result shape or ordering, a minor gap given annotations carry the safety profile.

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 and limit) are already documented in the schema. The description restates which fields 'query' matches but adds no format, syntax, or matching-rule detail beyond it – 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), a specific resource (Chatway contacts), the matchable fields (name, email, phone), and explicitly negates the adjacent scope (conversation messages). An agent can separate this from search-conversations purely from the description text.

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 clause 'does not search conversation messages' gives a clear when-not condition that routes the agent toward the conversation-search sibling, but the alternative tool is not named and no other prerequisites (e.g., required access level) are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful scope context by noting the search index excludes message bodies and that results are limited to 'accessible' conversations (permission-filtered). It does not mention ordering, pagination, or total-count behavior, which are the remaining gaps.

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 positive scope stated first and the exclusion plus routing instruction immediately after. Every clause earns its place.

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

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

For a simple two-parameter read tool with annotations covering safety, the description is nearly sufficient and even hints that conversation IDs are returned. Without an output schema, a brief note on result ordering or how partial matches behave would close the last gap.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description reinforces which fields 'query' matches but adds no syntax, matching mode (exact vs substring), or behavior for 'limit' beyond the schema default of 20. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

States a specific verb+resource ('Search accessible Chatway conversations') and enumerates the searchable fields (email subject, origin URL, contact name/email). It also explicitly carves out what it does not cover ('does not search message bodies'), which separates it from message-retrieval 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?

Provides both when-to-use (find conversations by subject/URL/contact) and when-not (message body content), plus the routing instruction to use returned conversation IDs to retrieve messages. An agent does not have to guess at an alternative path.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the 'authenticated team's' scoping largely restates the closed-world hint. The description adds no return shape, pagination, or result-size behavior beyond the schema's limit field.

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 first states scope, the second states intended use. Nothing is redundant and the purpose 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 two-parameter read-only search with no output schema, the description covers data scope, intended use, and a grounding instruction, which is enough to call it correctly. Minor gap: no guidance on result volume or how to route between this and the conversation/contact search siblings.

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% — both 'query' and 'limit' are documented in the schema itself. The description adds no format, syntax, or matching-behavior detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Search the authenticated team's Chatway knowledge-base questions and answers'), which is clearly distinct from siblings like search-conversations or search-contacts. It does not explicitly name or contrast with those siblings, so it stops short of a 5.

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

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

It gives a clear downstream purpose ('Use the returned content to answer or draft a response without inventing unsupported information'), which tells the agent when this tool is appropriate. It offers no exclusions or explicit alternatives (e.g. when to prefer search-conversations), so it is not a 5.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and readOnlyHint=false, so the agent knows this is an irreversible outward-facing write. The description's 'creates an external side effect' largely restates that, and it adds only the customer-visible framing; it says nothing about editability/retraction after send, permissions, 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?

Two sentences, zero filler, with the core action stated first and the guardrails immediately after. Every clause 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 two-parameter send tool with no output schema and annotations that already carry the safety profile, the description covers purpose, side-effect nature, and two important exclusions. It is nearly complete; only parameter detail and post-send behavior are absent, which the annotation set partly offsets.

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% (conversation_id has no description) and the description adds no parameter-level detail beyond implying the target is a Chatway conversation. With one of two parameters undocumented in the schema, the description does not compensate, so this sits at the baseline rather than above it.

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

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

States a specific verb (send), resource (reply in a Chatway conversation), and a distinguishing qualifier: the message is 'customer-visible' and sent 'as the authenticated agent'. That customer-visible framing separates it from internal siblings like add-note or add-custom-data without needing 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 explicit negative guidance: don't use it for drafts or after handoff has been requested, which directly references the handoff-to-human sibling concept. It stops short of naming the alternative action/tool for those cases, so it is clear context rather than a full when/when-not/alternative matrix.

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 non-read-only, non-destructive, closed-world mutation, so the safety profile is covered. The description adds real behavioral context beyond that: it is a batch operation and it enforces a confirmation step before mutating state. It doesn't state permission requirements or what happens to downstream state.

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, and the mutation target is front-loaded before the batching and confirmation instructions. Every clause carries actionable information.

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

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

For a two-parameter mutation with no output schema, the description covers the action, the batching model, and the confirmation prerequisite. It would be stronger with a note on required permissions or the effect on already-open conversations, but nothing critical 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 only 50% (conversation_ids is undocumented in the schema), so the description must compensate, and it does: it tells the agent to pass all target UUIDs in one call, clarifying the array/batch semantics. The confirmation_token flow is partly echoed from the schema's own description rather than extended.

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 ('Reopen ... resolved Chatway conversations') and states the batch scope ('one or more'). This makes it clearly the inverse of the sibling resolve-conversation, though it never names that sibling explicitly, which is the only thing separating it from 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?

It gives concrete operational guidance: pass all UUIDs in a single call, and obtain user confirmation before the status change. What's missing is an explicit when-not-to-use or a pointer to resolve-conversation as the counterpart, 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 destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds that it operates on an *existing* field (implying it errors or is a no-op otherwise), but does not say what happens if the field is absent, whether the operation requires the visitor to exist, or what the response looks like. Modest added value over 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 with zero filler; the primary action is front-loaded and the routing hint follows. Nothing redundant with 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 destructive, three-parameter mutation with no output schema and zero schema descriptions, the definition covers the sibling routing but omits failure behavior for a missing field, whether the field is created implicitly, and any return information. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description carries the burden for three parameters. 'value of an existing custom field' loosely maps name->field and value->replacement, but visitor_id is never characterized (ID format, where to obtain it) and no parameter semantics are stated explicitly.

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 ('Replace the value') plus a precise resource ('existing custom field on a Chatway visitor/contact'). It also explicitly differentiates itself from the sibling add-custom-data, so an agent can pick correctly 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?

States the selecting condition for the alternative route: use add-custom-data when the field does not exist. This is an explicit when-to-use-this vs when-to-use-that rule, 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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the useful negative signal that only definitions, not visitor values, are returned, but says nothing about pagination, ordering, or volume of results.

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 positive statement of behavior front-loaded and the disambiguation immediately after. No filler or restated boilerplate.

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, parameterless list tool with no output schema, the description covers what is listed and what is not. The only residual gap is that the shape of the returned definitions is left entirely to inference.

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; the baseline for a parameterless tool applies. No misleading parameter claims are made.

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

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

States a specific verb (List) and resource (custom-field definitions) plus the scope (available to the authenticated Chatway team). The second sentence disambiguates it from the value-oriented siblings such as add-custom-data and update-custom-data by explicitly ruling out visitor field values.

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 clarification 'does not return field values for a particular visitor' implicitly tells the agent this is not the tool for reading values, but it never names the alternative to use instead. Usage is only implied rather than an explicit when-to-use/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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine value by disclosing the returned content (tag names and colors) and the tenant scoping, but says nothing about ordering, pagination, or limits on the 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?

A single front-loaded sentence that identifies the action, the scope, and the payload with no filler. Nothing can 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?

For a parameterless, read-only listing tool with annotations covering safety and no output schema, the description supplies the missing return-content detail (tag names and colors). Only the absence of any statement about result size or ordering keeps it 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The mention of 'names and colors' refers to output, not input, and is not misrepresented as a parameter.

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: 'List the tags available to the authenticated Chatway team.' An agent can distinguish this read operation from the add-tag/remove-tag siblings by the verb alone, 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?

Usage is only implied — listing tags is naturally the step before add-tag, remove-tag, or assigning tags, and the phrase 'available to the authenticated Chatway team' scopes the result set. There is no explicit when-to-use statement or exclusion pointing to a sibling tool.

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