Chaport MCP by usefulapi

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds genuinely new context: the returned message text originates from website visitors and must be treated as data, not instructions. It also discloses the underlying endpoint, helping the agent understand scoping. It stops short of covering pagination or event-volume 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?

Front-loaded with the primary action and payload in the first clause, followed by a short safety note and the endpoint. Every sentence carries information, though the trailing GET path is marginally redundant with the structured name.

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

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

With no output schema, the description compensates by enumerating the returned fields (events, stage, operators, team, rating, start page). For a 4-parameter read-only lookup with full schema coverage, an agent has everything needed to call it correctly and interpret the response.

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 required and optional parameters including transcript and event_types are already documented with examples in the schema. The description mentions "its events (messages)" but adds no semantics for the transcript or event_types switches; 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?

Uses a specific verb+resource ("Get one chat of a visitor by chat id") and enumerates the payload contents (events, stage, assigned operators and team, rating, start page), which makes the result set concrete. It does not explicitly distinguish itself from chaport_get_last_visitor_chat or chaport_list_chat_events, so it falls short of full sibling differentiation.

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

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

Usage is only implied: the required visitor_id + chat_id pair tells an agent this is a point lookup rather than a listing, but there is no explicit "use this when / use X instead" guidance. Nothing tells the agent when to prefer chapters like chaport_list_chat_events or chaport_get_last_visitor_chat.

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 and openWorldHint=true, so safety is covered. Beyond that the description only restates the REST path; it adds nothing about what happens when the event or chat does not exist, permission requirements, or any scoping 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 short sentences, zero waste, with the action stated first and the endpoint as supporting detail.

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

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

A simple three-parameter read whose annotations and schema are complete, but with no output schema the description leaves unanswered what a 'chat event' contains or how a missing id is surfaced. Adequate for selecting the tool, thin for predicting the result.

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

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

Schema description coverage is 100% and each parameter documents its origin tool, so the schema carries the semantic load. The description contributes no additional parameter meaning, which is the baseline-3 case.

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

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

The description states a specific verb and resource — 'Get one event of a chat by event id' — and the singular 'one event' implicitly contrasts with the sibling chaport_list_chat_events. It is unambiguous about scope, though it never names the alternative explicitly.

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

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

Usage is only implied: fetch a single event when you already have an event id. The routing hint lives in the schema ('from chaport_list_chat_events') rather than the description, and there is no explicit when-not or alternative 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 only declare readOnlyHint and openWorldHint; the description adds real value beyond that by enumerating what the response contains (stage values, assigned operators/team, rating, missed flag) and by disclosing the GET endpoint. It also carries an important prompt-injection warning about visitor-authored message text. It does not say how many events are returned or whether the list is truncated, which is the remaining behavioral 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?

Front-loaded with the core purpose, then dense clauses that each carry information (stage values, links.more behavior, injection warning, endpoint). It is a long single block of clauses rather than clearly separated sentences, which slightly hurts scanability but wastes no words.

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

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

No output schema exists, so the description must carry the return-value burden, and it does so thoroughly by naming the fields an agent would act on. The only omissions are transcript-mode behavior and any indication of event limits or pagination.

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 transcript and event_types are already well documented in the schema, which sets the baseline at 3. The description adds little parameter-level detail and never mentions the transcript mode that materially changes the return shape, so it does not exceed the baseline.

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

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

Specific verb and resource: 'Get a visitor's current or most recent chat' with an explicit enumerated payload (events, stage, operators, rating, start page, missed). It also names the sibling boundary by pointing at chaport_get_chat for older chats, so an agent can distinguish it from chaport_get_chat and chaport_list_chat_events 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?

Implies the selection rule (latest chat for a visitor) and explicitly routes to chaport_get_chat for older chats via links.more numeric ids. There is no explicit when-not or a comparison against chaport_get_chat_event or chaport_list_chat_events, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the REST endpoint and the returned field set, which is useful context, but says nothing about behavior on an unknown/deleted id or any rate/permission considerations.

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: the field list comes first and the endpoint second. Nothing is repeated from the title and nothing could be cut 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 one-parameter read tool with no output schema, listing the returned fields is exactly the right compensation, and annotations cover the safety profile. Only the not-found/error behavior 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% and the only parameter is already documented in-schema as "Operator id (from chaport_list_operators)." The description adds no format or provenance detail 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 one operator by id") and enumerates the fields returned, plus the underlying endpoint. The singular "one ... by id" implicitly contrasts with chaport_list_operators, but the sibling is never named, so the differentiation is inferential rather than explicit.

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 single-record fetch implies the use case (look up one operator's details once the id is known), and the schema notes the id comes from chaport_list_operators. However, the description itself offers no when-to-use vs. when-to-use-list guidance and no 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 cover safety (readOnlyHint=true, openWorldHint=true), so the description's added value is the disclosure of what comes back — full contact data, notes, UTM data, browser/OS and custom fields — which is useful given no output schema exists. It omits any note about the error/not-found behavior or whether the response is a single flat object.

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 followed by the returned payload and the underlying endpoint. No filler.

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

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

With one trivially documented parameter and no output schema, the description does the needed work by enumerating the returned fields. Only minor gaps remain (not-found behavior, response shape), which is acceptable for a simple read tool with readOnlyHint declared.

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 parameter is already documented with its provenance ("from chaport_list_visitors"), so the baseline is 3. The description's "by id" adds nothing 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 ("Get one visitor by id") and enumerates the data returned (contact data, notes, UTM, browser/OS, custom fields), which clearly separates it from list-style siblings. It never names the sibling to prefer for bulk retrieval, so differentiation is implied rather than stated.

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

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

The phrase "by id" plus the schema note pointing at chaport_list_visitors implies the workflow (list first, then fetch one), but the description itself gives no explicit when-to-use or when-not guidance and does not mention chaport_get_last_visitor_chat as the alternative for the most recent visitor's chat.

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

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

Beyond the readOnlyHint annotation, the description adds useful behavioral context: events are returned in order, the event categories are listed, and it includes an important prompt-injection warning that visitor message text should be treated as data, not instructions. It does not discuss pagination or result limits, but the annotations already establish that this is a safe read operation.

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

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

The description is compact and front-loaded: it states the core purpose first, then enumerates event types, then adds the safety warning. Every sentence contributes useful information with no filler.

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

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

Given the readOnly/openWorld annotations, fully documented parameters, and absence of an output schema, the description supplies enough context for an agent to call this tool correctly. The enumerated event types and prompt-injection warning are particularly relevant additions.

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 well described in the schema itself, including where to obtain chat_id and visitor_id. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 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?

The description gives a specific verb and resource: list all events of one chat, in order. It enumerates the event types (visitor/operator messages, trigger messages, invitations, email requests, opened pages), which makes the tool's scope unambiguous compared with siblings like chaport_get_chat_event.

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 clearly implies the use case of retrieving a chat's event history, but it does not explicitly say when to use this versus chaport_get_chat_event or chaport_get_chat. Usage is inferable from the purpose statement 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 and openWorldHint=true, so the safety profile is covered by structured data. The description adds the concrete result shape (id, name, email, role, job title, login/activity, lastStatus/realStatus) and the endpoint, but says nothing about result set size, ordering, or whether inactive operators are included.

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

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

A single dense sentence front-loads the action and resource, then the returned fields, then the endpoint. No filler or repetition.

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

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

With no output schema, the field enumeration in the description does real work in telling the agent what comes back, which is the main completeness requirement here. Minor gap: no indication of whether the list is paginated, ordered, or includes deactivated operators.

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 description correctly signals that no filtering arguments are accepted by implying an unfiltered 'list all'.

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

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

States a specific verb and resource ("List all operators (team members) of the Chaport account"), clarifies the domain term operator = team member, and enumerates the returned fields plus the underlying endpoint GET /operators. It doesn't explicitly contrast with the sibling chaport_get_operator, though the name pair makes the singular/plural distinction reasonably inferable.

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 by "List all operators of the Chaport account" – an agent can infer this is the bulk-fetch counterpart to chaport_get_operator, but nothing is stated about when to prefer one over the other or any prerequisites. No alternatives or exclusions are named.

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 and openWorldHint=true, so the safety profile is covered. The description adds ordering semantics, the pagination cursor field (links.next), and the underlying endpoint GET /visitors — genuinely additive. It stops short of stating page size or total-count behavior, which would be the final piece.

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

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

Two sentences, front-loaded with the resource and ordering, then pagination, then the escape hatch to the sibling. 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 paginated list with no output schema, the description compensates by enumerating the returned fields and explaining the pagination cursor. An agent can both invoke it correctly and know what to expect back without a return schema.

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

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

With only one parameter and 100% schema coverage, the baseline is 3, but the description exceeds it by explaining how 'page' interacts with the response's links.next ('call again with page + 1'), which the schema alone does not convey.

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

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

States a specific verb and resource ('List visitors (website contacts)') plus the ordering rule ('most recent chat first') and the field set returned. This clearly separates it from chaport_get_visitor (single record) and chaport_get_last_visitor_chat (conversation view).

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 continuation instructions ('Use links.next in the reply for the next page (call again with page + 1)') and routes the agent to the named sibling with the selecting condition: 'To read someone's conversation, pass the visitor id to chaport_get_last_visitor_chat.' Nothing is left to inference about follow-up behavior.

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 and openWorldHint=true, so safety is covered. The description adds account-scoped behavior, the concrete fields returned, and the HTTP route, which goes beyond the annotations; only pagination/result-size behavior is left unstated.

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 front-loaded sentence naming the resource first, then the returned fields, then the endpoint. Zero filler.

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

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

With no output schema, the description usefully enumerates the returned fields (id, URL, events, creation time). For a no-param list tool this is nearly complete; only pagination or ordering hints are missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies.

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

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

Specific verb + resource ('List the account's webhook subscriptions') plus the returned fields and the underlying endpoint. No sibling tool deals with webhooks, so the scope is unambiguous against the chat/operator/visitor tools.

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?

Implicitly clear: a zero-parameter read call whose only use is to enumerate webhook subscriptions, and no sibling offers an overlapping capability. No explicit when-not-to-use clause, but there is also no alternative to route to.

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

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

Adds substantial context beyond the destructiveHint=true annotation: the message is really delivered and visible in the visitor's widget, may reach them on a connected channel, cannot be undone from this tool, and has the side effect of creating a new chat. It also explains the conditional idempotency semantics of external_id, which is exactly the nuance the flat idempotentHint=false annotation 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?

The consequence and irreversibility are front-loaded in the first two sentences, followed by the confirmation protocol and the retry mechanism. Every sentence carries operational information; nothing is repeated from the schema or annotations.

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

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

For a destructive, open-world send with four required parameters and no output schema, the description covers side effects, irreversibility, and the confirmation gate well. It does not state what a successful call or a deduplicated retry returns (e.g., a message id), which is the one remaining 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 baseline is 3, but the description earns extra credit by explaining the confirm gate as a user-approval contract and by defining external_id's idempotency scope (same id + same visitor's latest chat = duplicate). The 5000-character text limit and id sourcing remain schema-only concerns.

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 with scope: sends a real outbound message to a website visitor in their Chaport chat as a given operator. It also distinguishes itself behaviorally from the read-oriented siblings by stating that a new chat is started when no recent one exists, so an agent can tell this apart from chaport_get_chat or chaport_update_last_visitor_chat.

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 pre-call protocol (confirm text and recipient with the user first, then pass confirm: true) and a retry policy (use external_id for safe retries). It also indirectly routes the agent to chaport_list_visitors and chaport_list_operators via the schema. It stops short of naming a sibling to use instead for adjacent cases, so it is clear context without explicit alternatives.

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

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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, so the description's job is to add context—and it does: the status persists until expiry or until someone else changes it, and it changes chat routing. That persistence/overwrite semantics is exactly the behavior an agent needs to reason about the non-idempotent, destructive hints. It does not, however, say what happens to already-assigned chats or whether the call returns anything.

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

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

Three short sentences, front-loaded with the action and the value examples, then the expiry rules. The sentence about the status staying in effect is slightly redundant with the ttl/valid_until framing but still carries the distinct point that others can override it.

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

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

For a 4-parameter mutation with annotations covering the risk profile and full schema coverage on parameters, this is nearly complete—it explains timing, exclusivity, persistence and side effects. The remaining gap is what happens to in-flight chat assignment and whether anything is returned, which matters mildly given there is no output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by adding the mutual-exclusivity constraint ("give exactly one of the two") that the schema does not encode—there is no oneOf in the input schema. It also cross-references chaport_list_operators for valid status names and operator ids, which the schema descriptions only partially do.

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 ("Set an operator's status") with concrete value examples (online, away, offline) and even names the endpoint POST /operators/{operatorId}/status. No sibling tool performs status changes, so the agent can distinguish it immediately from list/get/update tools in the same family.

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

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

Usage is implied rather than stated: the description explains the effect ("Changes who gets new chats") and the exactly-one-of rule for the two timing parameters, but never says when an agent should prefer this over, say, sending a message or leaving the operator untouched. Since no true alternative exists in the sibling set, the implicit guidance is probably sufficient, but it is not explicit.

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

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

Adds real consequence beyond the annotations: 'Reassigning changes who sees the chat' and the []-unassign behavior. With destructiveHint=true already declared, it would be stronger if it said what is lost or whether changes are reversible, but the added context is genuine.

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: mutation scope and field behaviors first, partial-update rule and endpoint last. 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 a 5-param mutation with no output schema, it covers the essential mechanics: partial updates, reassignment effect, unassignment syntax. It omits where operator/team ids come from and what the call returns, leaving a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema cannot: operators=[id] assigns and operators=[] unassigns, and stage change means e.g. closing. That is meaningful added meaning over the schema descriptions.

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 (update) plus the exact resource (visitor's current or most recent chat) and enumerates the mutable fields. It cleanly separates itself from siblings like chaport_get_last_visitor_chat (read) and chaport_update_visitor (visitor, not chat).

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

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

Gives concrete usage scenarios — reassign, unassign, close, flag as missed — and the partial-update contract 'Only the fields you pass change'. It does not name an alternative tool or state when not to use it, so it falls short of a 5.

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

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

The annotations already declare idempotentHint, destructiveHint, and openWorldHint, so the safety profile is partly covered structurally. The description adds valuable behavior beyond annotations: only supplied fields change, the updated visitor is returned, and the operation maps to PUT /visitors/{visitorId}.

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

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

The description is three short sentences, front-loaded with the action and affected fields. Every sentence contributes either scope, update semantics, return behavior, or endpoint context.

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 nested utm/custom objects, one required ID, full schema coverage, and annotations covering idempotency and destructive behavior, the description is nearly complete. It could say more about permissions, side effects, or prerequisites, but nothing critical for 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 the baseline would be 3, but the description adds meaningful semantics about partial updates: 'Only the fields you pass change.' That clarifies how all optional parameters behave in a way the schema alone does not.

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 ('Update a visitor'), then enumerates the contact fields affected. This clearly distinguishes it from sibling read tools such as chaport_get_visitor and chaport_list_visitors.

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 purpose: use this to change an existing visitor's contact data. However, it gives no explicit when-to-use guidance, prerequisites, or comparison to alternatives, and does not state when not to use it.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds that it issues GET /me.json and returns Chaport's raw response, which tells the agent the output is an unnormalized API payload rather than a tool-shaped object. It does not state what an auth failure looks like, which is the main remaining gap.

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

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

Two short sentences, front-loaded with the purpose and ending with the concrete endpoint. No wasted words.

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 trivial zero-param read with no output schema and safety already covered by annotations, the description is nearly sufficient. The only shortfall is that it never characterizes the returned payload (fields, error shape), which an agent would have to discover by calling it.

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

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

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. Nothing in the text misleads about inputs.

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: confirm the connected access token works and show the raw /me.json payload. This is clearly a connection/auth diagnostic, distinct from siblings like chaport_get_operator or chaport_list_operators which retrieve entity data rather than validate credentials.

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 makes the use case obvious (verify the token before/while using other tools), giving clear context for invocation. It does not explicitly say when not to use it or name an alternative, but for a zero-arg healthcheck there is no real competing tool.

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