HelpCrunch MCP by usefulapi

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

The destructiveHint=true annotation already flags this as a mutating operation, and the description corroborates it by stating the tool can both assign AND unassign, so the destructive half is not hidden. It adds the REST endpoint and the dual-mode behavior, but says nothing about permissions, whether reassignment silently overwrites a prior assignee, or whether the target agent is notified.

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

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

Three short, front-loaded sentences with no filler; the assign/unassign contract comes before the endpoint detail. The trailing REST reference is mildly extraneous for an agent but costs almost nothing.

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

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

For a 2-parameter tool with full schema coverage and no output schema, the description covers what it is, how the optional parameter switches behavior, and the underlying endpoint. Missing permission/authorization expectations and the effect on any previously assigned agent keep it from a 5.

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

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

Schema description coverage is 100%, so both 'id' and 'assignee' are already documented in the schema; baseline is 3. The description restates the omit-to-unassign contract, which mildly reinforces the schema rather than extending it (no format/syntax details added).

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 ('ASSIGNS ... a LIVE chat to an agent') and explicitly covers the inverse operation (unassign), which no sibling tool does. An agent can distinguish this from helpcrunch_update_chat_status purely from the description.

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

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

It clearly explains the conditional usage of the assignee parameter (present = assign, omitted/null = unassign), which is real operational guidance. It does not, however, say when to prefer this tool over siblings like update_chat_status, nor mention prerequisites such as being an agent/admin.

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 carry only destructiveHint=true, so the description carries most of the disclosure burden. It usefully flags that the target is a LIVE chat and that one mode is customer-visible, hinting at immediacy and irreversibility, but it does not state whether messages can be edited/retracted, what permissions are required, or any 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?

Three tight sentences with the core operation and mode distinction front-loaded, then parameter guidance, then the REST endpoint. 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?

For a write tool with no output schema, the definition covers what is created, where it lands, and how the two modes differ. It leaves gaps around auth/permissions and post-creation lifecycle, but nothing essential for invoking the call correctly is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description restates the type enum and the agent-omission rule almost verbatim, adding little beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (POSTS) and resource (a message) and immediately distinguishes the two modes: customer-visible reply (type "message") vs internal private note (type "private"). The reader can separate this from read-side siblings like helpcrunch_get_chat_messages or helpcrunch_get_chat without opening a schema.

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

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

Gives clear selection context for the two modes and for when to set `agent` versus omit it for customer messages. It does not name a competing sibling or a when-not-to-use condition, so it falls short of the explicit routing seen in top-tier definitions.

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, so the safety profile is covered. The description adds only the REST endpoint mapping (GET /chats/{id}), with no mention of error behavior, permissions, or what a chat object contains. With annotations carrying the load, this is adequate but thin.

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, with the core action front-loaded and the endpoint detail second. Every element earns its place.

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

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

For a single-parameter read tool with rich schema coverage and readOnlyHint annotation, the definition is nearly self-sufficient. The only minor gap is that with no output schema, nothing hints at the shape of the returned chat.

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 explains the id fully ('numeric id, passed as a string'). The description's 'by id' adds nothing beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a single chat (conversation) by id'), which clearly separates it from sibling list_chats and get_chat_messages. It stops short of naming those siblings explicitly, so it's clear but not fully differentiated.

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

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

The description gives no when-to-use guidance, no prerequisites, and does not name alternatives such as list_chats or get_chat_messages. The 'by id' phrasing implicitly assumes the caller already has an id, but nothing about context or exclusions is 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, so the safety profile is covered. The description adds genuine behavioral detail beyond that: results are sorted newest first by createdAt DESC, limit is capped at 100, and pagination is via limit/offset, plus the underlying REST route. No auth or rate-limit context 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 compact sentences, front-loaded with the core action and ordering, then pagination and the endpoint reference. 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?

For a simple read-only list tool with full schema coverage and no output schema, the description covers action, ordering, and pagination adequately. It omits minor details such as the default page size and the message fields returned, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented, and the description largely restates the limit max of 100 and offset pagination. It adds no new syntactic or format meaning (e.g., default limit or ordering interaction with offset), 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?

Names a specific verb and resource ('get the messages of a chat'), and disambiguates the resource by glossing 'chat (conversation)'. It is clearly distinct from helpcrunch_get_chat and helpcrunch_list_chats, though it doesn't explicitly name those 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?

Usage context is implied: fetch the messages belonging to a known chat id, with pagination hints (limit/offset) for large threads. There is no explicit when-to-use versus alternatives such as helpcrunch_list_chats or helpcrunch_get_chat, and no stated prerequisites.

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

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

Annotations already declare readOnlyHint=true, so the safe read-only nature is covered. The description adds the underlying REST mapping (GET /customers/{id}), which is mild useful context, but says nothing about not-found/error behavior or the returned payload for this id-only lookup.

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, with the core action stated first and the endpoint mapping second. Nothing is padded or repeated.

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

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

For a single-parameter read tool with annotations covering the safety profile and no output schema to explain, the description is nearly sufficient. It only lacks a pointer to the sibling list tool for id discovery, which is a minor gap.

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

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

Schema description coverage is 100% and the single id parameter is fully documented in the schema (numeric id passed as a string). The description adds no format, syntax, or example detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get a single customer by id'), and the word 'single' implicitly separates it from helpcrunch_list_customers. However, it never names that sibling or any other alternative, so differentiation must be inferred from the name alone.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The 'by id' phrasing implies the tool requires a known customer id, but the description never states that a lookup/list should precede it, nor mentions any alternative tool.

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?

readOnlyHint=true already establishes a safe read, and with no output schema the description usefully discloses the return shape (domain string, teamOnline and chatEnabled booleans), which is genuine added context. It stops short of describing error behavior or rate limits, but for a simple availability read this is sufficient.

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

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

A single dense sentence leads with the resource and its key fields, then appends the REST endpoint. No filler, no restatement of the title, and the most decision-relevant information 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 parameterless read-only tool, the description covers what it is, what it returns, and the underlying endpoint, with annotations handling the safety profile. The only gap is the absence of any usage framing or error/auth notes, which is minor at this complexity.

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

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

The tool takes zero parameters, so per the calibration baseline a 4 applies. There is nothing for the description to disambiguate, and it correctly adds no parameter noise.

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

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

States a specific verb ('Get') and resource ('organization') and then enumerates the exact payload fields (domain, teamOnline, chatEnabled). This cleanly distinguishes it from all siblings, which operate on chats, customers, agents, and departments.

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 nature of the response (live-chat availability) implies the use case — checking whether the team is online before routing a message — but the description never states when to call this versus alternatives like helpcrunch_list_departments or helpcrunch_list_agents, nor any prerequisites.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context beyond that: the pagination mechanism and the exact REST endpoint (GET /agents). It does not mention auth requirements, rate limits, or default page size, so it adds only moderate behavioral value.

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 plus the endpoint reference, front-loaded with the core purpose and zero filler. Every clause carries information the 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 read-only, two-parameter list tool with full schema coverage and annotations covering safety, the description is nearly complete. Naming the returned fields (role, email) compensates for the absent output schema, though it could mention ordering or default pagination 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 coverage is 100% and both parameters are fully documented in the schema. The description restates 'paginate with limit/offset' without adding syntax or default values, so it neither helps nor hurts. 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 ('List agents') and disambiguates what an agent is ('support staff / operators') plus the fields returned (role, email). It doesn't explicitly differentiate from siblings like helpcrunch_list_customers or helpcrunch_list_departments, but the resource is distinct enough that an agent can pick it without confusion.

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

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

Usage is implied by the nature of a list endpoint, and the description notes pagination with limit/offset, but it offers no explicit when-to-use or when-not-to-use guidance relative to the other list_* tools. Adequate minimum without 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=true, so the safety profile is covered. The description adds modest value by naming the upstream REST endpoint (GET /applications) and the entity types returned, but says nothing about result size, pagination, or authentication scope — with annotations carrying the safety signal, a 3 is appropriate.

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 compact sentence with the resource and return fields front-loaded, plus a short endpoint reference. The parenthetical field list (id, name, displayName, active, type) earns its place given there is no output schema; the REST endpoint note is mildly redundant with the tool name but useful for mapping to HelpCrunch docs.

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 field enumeration is exactly the kind of return-value context an agent needs, and a zero-parameter read-only list has few other unknowns. Only pagination/volume behavior is left unaddressed, which is a minor gap for this tool's 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?

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate and no risk of parameter misuse. A 4 is the neutral ceiling here rather than a demonstration of added semantic value.

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

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

States a specific verb (List) and resource (applications configured in the account) and immediately disambiguates the uncommon term 'application' by enumerating what counts: web chat widgets, mobile apps, and social integrations. Sibling tools operate on chats, customers, agents, and departments, so this is clearly distinguishable.

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: a zero-parameter enumerator is naturally the entry point for discovering application IDs, but the description never says when to call it, what prerequisite IDs it feeds, or whether pagination/filtering apply. No alternative or exclusion is named, though none is obviously needed here.

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

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

Annotations declare readOnlyHint=true, so the safety profile is already covered; the description adds genuinely new behavioral context, notably the constraint that only a single field/operator/value clause with AND comparison is supported, plus the sort/pagination model. It still omits return shape and any rate-limit or result-count behavior, so it is strong but not exhaustive.

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: purpose first, then the filter/sort/pagination capabilities, then the underlying endpoint. Every sentence carries information and none is redundant with the schema.

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

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

For a 7-parameter, read-only listing tool with no output schema and minimal annotations, the description covers filtering, sorting and pagination adequately. It could say more about what a result set contains or default limits, but it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, giving a baseline of 3, but the description adds meaning beyond the schema by explaining that field, operator and value compose a single AND clause and that sort/order pair together with an example field (chats.createdAt). That compositional constraint is not stated in the schema itself.

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 / search chats (conversations)') and even names the backing REST endpoint (POST /chats/search), so the agent knows this is a collection-listing/query tool rather than a single-fetch tool. It does not explicitly name a sibling such as helpcrunch_get_chat to contrast with, 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 conveys the mechanics of use (filter with a single field/operator/value clause, sort plus order, limit/offset) but never states when to choose this tool over helpcrunch_get_chat or helpcrunch_get_chat_messages, nor any prerequisites. Usage is implied by the operation rather than explicitly guided.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely non-obvious behavior: that reads are implemented as 'POST /customers/search' and that only a SINGLE field/operator/value clause is supported (AND-comparison only), which is a real constraint an agent must respect.

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 front-loads what the tool does, the second enumerates the three optional capabilities plus the backing endpoint. No filler, no repetition 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 an all-optional, 7-parameter search tool with no output schema, the description covers filtering, sorting and pagination adequately. It stops short of noting default or maximum limit behavior and gives no hint about what customer fields come back, which a fully complete definition would include.

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 seven parameters are already documented in the schema with examples and enums. The description only restates the filter/sort/paginate grouping and adds that field+operator+value form one clause; it contributes little 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?

States a specific verb+resource ('List / search customers') and immediately disambiguates the resource with a parenthetical ('people who chatted in'). It implicitly separates itself from the singular helpcrunch_get_customer, though it never names that sibling.

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 describes the optional capabilities (single filter clause, sort, pagination) so an agent can infer how to use it, but it never states when to reach for this tool instead of helpcrunch_get_customer or helpcrunch_list_chats, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: departments are returned with their nested agents, and the underlying call maps to REST GET /departments. It says nothing about auth requirements, result caps, or response envelope, so it is additive but not rich.

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 clauses plus an endpoint reference, with the resource definition front-loaded. Every phrase earns its place and nothing is padded.

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

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

For a zero-required-parameter, read-only list tool with no output schema, the description covers purpose, return structure, and pagination adequately. It stops short of describing the response envelope (e.g. total counts or pagination metadata), which is the only notable gap.

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

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

Schema description coverage is 100% and both parameters are already documented in the schema, so the baseline is 3. The description's 'Paginate with limit/offset' only restates the parameters without adding format, defaults, or bounds information.

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 departments') and even defines the resource inline as 'groups of agents that chats can be routed to'. It also clarifies the return shape ('each with its agents'), which implicitly separates it from helpcrunch_list_agents, though it never names that sibling explicitly.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternative. The only operational hint is pagination ('Paginate with limit/offset'), which is a mechanics note rather than usage guidance.

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

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

Annotations already declare destructiveHint=true, so the mutation risk is covered; the description adds that it targets a LIVE chat and maps to PUT /chats/status. It does not disclose side effects such as customer notification, whether the change is reversible, or permission requirements, so it adds only modest value beyond the annotation.

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

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

Two compact sentences with the action front-loaded and no filler. The trailing REST endpoint line is marginally useful metadata rather than essential agent guidance, but nothing is padded.

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

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

For a two-parameter tool with full schema coverage and no output schema, the definition covers the operation and its valid values adequately. It omits only secondary details like side effects or auth requirements, which keeps it from being fully complete.

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

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

Schema coverage is 100% and the enum already documents valid statuses; the description simply repeats a subset of those enum values ('opened, pending, on hold, or closed'). No extra semantics about the id or status transitions are provided, so the baseline of 3 applies.

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

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

States a specific verb and resource ('CHANGES the status of a LIVE chat') plus concrete status examples, which lets an agent distinguish it from sibling list/get/assign tools. It stops short of naming an alternative sibling it could be confused with, so it lands just below the top tier.

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

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

The description gives example status values but never states when to use this tool versus helpcrunch_assign_chat or helpcrunch_create_message, nor any prerequisites (e.g. the chat must already exist). Usage must be inferred from the verb alone.

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