Chatra MCP by usefulapi

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so safety is largely covered. The description usefully adds that the operation is irreversible and that the deleted message is returned, plus the underlying endpoint, but it says nothing about failure modes (e.g. attempting to delete a visitor message) beyond the exclusion.

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 WRITE, IRREVERSIBLE warning front-loaded before the operation and the scope restriction. Nothing is padded or redundant.

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

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

For a one-parameter destructive tool with rich annotations and no output schema, the description covers effect, reversibility, scope restriction and return value. An agent has enough to call it correctly without further context.

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 and schema description coverage is 100%, so the schema already documents message_id as the Chatra message id and its source. The description adds only the path template DELETE /messages/{id}, which confirms it is a path parameter but adds no new semantics.

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

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

States a specific verb (delete) and resource (an agent message) and scopes it to the conversation, which implicitly separates it from the pushed-message siblings. It never names chatra_delete_pushed_message or chatra_edit_message explicitly, so an agent must infer which of the delete/edit variants applies.

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 hard exclusion — only agents' messages can be deleted, not visitors' — which prevents the most likely misuse. It does not name a fallback tool when the target is a visitor message or a pushed message, leaving the agent to search 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 idempotentHint=true, so the safety bar is low; the description nonetheless adds 'IRREVERSIBLE' as an explicit severity callout and discloses the return value ('Returns the deleted message'), which is not in the annotations and no output schema exists. It does not state behavior when the message is already gone, but the added signal is above the annotation baseline.

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 irreversible-write warning front-loaded before the operation itself, so the risk signal is the first thing the agent reads. Every clause adds information; nothing repeats 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?

With one fully documented parameter, no output schema and destructive/idempotent hints already present, the description covers purpose, severity, and return value. The only absent detail is edge-case behavior (deleting an already-deleted or nonexistent message id), which is minor for this tool shape.

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

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

Schema coverage is 100% for the single message_id parameter, including provenance guidance ('from the reply of a send call or from a webhook'), so the schema carries the semantics. The description adds no format or origin detail beyond the URL template's {id} placeholder.

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

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

States a specific verb (delete) plus a qualified resource (pushed message, sent earlier), which separates it from the plain chatra_delete_message sibling by resource type. It also names the underlying endpoint, so the operation is unambiguous. It stops short of explicitly contrasting itself with chatra_delete_message, but the resource qualifier does most of that work.

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 the resource naming - an agent can infer this is for pushed messages and not, say, chatra_edit_pushed_message, but there is no explicit when-to-use or when-not-to-use statement and no alternative is named. The 'sent earlier' phrasing hints at scope but is not guidance.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the bar is lower. The description adds genuinely new context: the edit is visible to the visitor and only agent-authored messages qualify, which is not captured by any structured field. It doesn't cover failure behavior when the target message is a visitor message.

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

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

Four short sentences, front-loaded with the WRITE marker and the action, followed by the eligibility constraint, the user-visible effect, and the return value. Every sentence carries distinct information with no repetition.

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

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

For a two-parameter mutation with no output schema, the description covers what changes, who can see it, the eligibility rule, and the return value. Only edge behavior (errors on visitor messages, whether prior text is recoverable) is left implicit.

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

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

Schema description coverage is 100%, with both parameters documented (message_id source, text length bounds), so the baseline is 3. The description adds no parameter-level detail beyond what the schema already provides.

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

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

States a specific verb and resource ('replace the text of an agent message that was sent earlier') plus the underlying PUT endpoint. It is clearly distinguishable from siblings like chatra_send_message or chatra_delete_message without opening any schema.

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

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

Provides an explicit applicability constraint: only agents' messages can be edited, not visitors'. That is a real exclusion that steers the agent away from misuse. It stops short of naming alternatives (e.g. chatra_edit_pushed_message for pushed messages) when this tool doesn't apply.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, and the description corroborates the write nature while adding real context: the edit is visible to the visitor and the call returns the updated message. It does not explain that the previous text is discarded or what happens for a stale/invalid id, which is the main remaining gap for a destructive tool.

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

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

One dense sentence front-loaded with the WRITE marker, followed by the return value and endpoint. No filler; 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?

With no output schema, the description usefully states that the updated message is returned, and the endpoint hints at the underlying operation. It stops short of covering error behavior and permission requirements, which matters for a destructive, open-world mutation.

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

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

Both parameters are fully documented in the schema (100% coverage, including length bounds and where the id comes from), so the baseline applies. The description adds no parameter-level detail such as format of message_id or whether partial text replacement is allowed beyond what the schema states.

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 ('replace the text') and a specific resource ('a pushed message sent earlier'), plus the user-visible effect ('the visitor sees the edited text'). The 'pushed message' qualifier is what separates it from chatra_edit_message, though the description never names that sibling outright.

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?

Use is only implied: editing requires that the message already exists ('sent earlier'). There is no explicit when-to-use guidance, no statement of when to prefer chatra_edit_message instead, and no mention of preconditions such as failures on unknown message ids.

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=true, so the safety profile is covered. The description adds real context beyond that: the absence of any list endpoint and where a valid id originates. It doesn't mention error behavior for stale/unknown ids, which keeps it below 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 tightly written sentences, front-loaded with what is returned, followed by the id-provenance caveat. No filler, though the trailing 'GET /messages/{id}.' is redundant for an agent that cannot issue raw HTTP.

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 required parameter, full schema coverage, and no output schema, the description supplies exactly the missing pieces: the shape of the returned message and how to legitimately obtain the id. Nothing an agent needs to call this correctly is absent.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema with the same 'from the reply of a send call or from a webhook' provenance. The description restates that rather than adding new syntax or validity details, 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?

Names a specific verb and resource ('One chat message by id') and enumerates the payload fields the caller gets back (type, text, visitor id, agent id, timestamp, receivedFrom), so the agent knows exactly what it retrieves. It doesn't explicitly declare a boundary against chatra_get_pushed_message, the nearest sibling, so it falls short of a full 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?

Gives a genuine prerequisite: the id must come from a send call or a webhook because Chatra has no conversation-listing endpoint. That tells the agent when this tool is callable at all. It stops short of naming alternatives (e.g. get_pushed_message) when the id refers to a pushed message.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real context beyond that: the returned fields (text, visitor id, agent id, timestamp in ms, isPushed) and the underlying REST endpoint GET /pushedMessages/{id}, which matters because there is no output schema.

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

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

A single dense sentence with the resource identity front-loaded and the field list and endpoint trailing. Nothing is redundant, though the colon-separated field list is slightly compressed for scanning.

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, listing the returned fields is exactly the missing piece and it is present; the endpoint path also anchors the call. What remains absent is any failure behavior (e.g. unknown id) or usage framing, which keeps it short of 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 coverage is 100% and the message_id parameter already documents its origin (send-call reply or webhook). The description's 'by id' adds nothing new, so baseline 3 applies.

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

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

States a specific verb (get) and resource (a pushed/automated message) scoped to a single record by id. The parenthetical '(automated)' disambiguates it from chatra_get_message, so an agent can tell the two apart without opening schemas, though the sibling is not named explicitly.

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

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

The description never says when to use this versus chatra_get_message or chatra_push_message; the only implied guidance is 'by id'. No prerequisites, no exclusions, no alternative routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered; the description adds the concrete endpoint (GET /clients/{id}) and the fact that no list/search capability exists anywhere in the API. It does not say what happens on a missing/invalid visitor id or whether external integration data requires extra access, leaving some operational 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?

Three sentences, front-loaded with the resource, then the response payload, then the id requirement and endpoint. The long field enumeration earns its place because there is no output schema, though the id sentence partially duplicates 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?

With no output schema, describing the returned fields is the right compensation, and the description covers them thoroughly plus the endpoint. Missing only edge-case behavior (visitor not found, empty visit history) that an agent would need to interpret a sparse 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% and the single parameter's schema description already spells out clientId (ChatraSetup.clientId) and the webhook client.id. The description's id explanation essentially restates the schema, adding no format, encoding, or validation guidance beyond it, 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+resource ('A chat visitor by id') and enumerates exactly what the response contains (basicInfo, integrationData, merged info, custom form answers, location, browser, dashboard link, agent group, latest-visit pages). The resource is unambiguously distinct from the message-oriented siblings and from chatra_update_visitor.

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?

Explains the required id's provenance (clientId from the widget or the visitor id from a Chatra webhook) and explicitly warns that 'Chatra has no endpoint to list or search visitors,' which steers the agent away from a lookup strategy it might otherwise attempt. It does not contrast with chatra_update_visitor or describe behavior when the id is unknown, so it falls short of a full when/when-not treatment.

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 idempotentHint=false, so the bar is lower; the description still earns credit by making the destructiveness concrete ("reaches a real customer and cannot be unsent except by deleting it") and by stating the return payload and endpoint. No annotation contradiction; it doesn't cover error handling or whether agent_id and group_id can be combined.

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

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

Front-loads "WRITE:" as the operation class, then target, delivery semantics, irreversibility and return value in three dense sentences with no filler. Every clause carries decision-relevant information.

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

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

For a destructive, non-idempotent write with no output schema, the description supplies the essentials: destination, targeting options, consequence of misuse, and return value. The one gap is what happens on failure or when both agent_id and group_id are supplied.

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 schema already documents all four parameters including the random-agent semantics of group_id. The description's restatement of agent_id/group_id targeting and the clientId binding adds orientation but little meaning beyond the schema fields.

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

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

Opens with an explicit verb+resource ("send an automated message") and scopes the audience precisely: a visitor bound via clientId, delivered as a pushed/automated message (POST /pushedMessages/). That 'automated/pushed' framing implicitly separates it from chatra_send_message, but no sibling is named explicitly, so the differentiation is inferred 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?

Gives a real usage constraint ("only call it with text the user asked you to send") and explains the delivery precondition (account bound to Chatra via clientId). It stops short of naming alternatives such as chatra_send_message for live replies, or saying when a pushed message is preferred over a normal one.

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 destructiveHint/not-idempotent annotations it discloses what actually happens: the visitor sees it live as agent-typed text, it cannot be unsent except by deletion, unknown emails spawn a dummy agent, and the created message with its id is returned. That is exactly the extra context annotations cannot convey.

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

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

Front-loaded with the WRITE marker and the core action; the caution, the alternative, and the identity mechanics follow in order. Five sentences is dense for a write tool but each carries distinct information, with only mild packing in the agent-identity 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?

Covers the mutation's consequence, the reversibility caveat, the identity-parameter branches, the return value (new message + id), and the endpoint. With no output schema and full param coverage, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: the agent_id vs. agent_email+agent_name+received_from alternative, the required conjunction of fields, and the dummy-agent side effect. It stops short of explaining what received_from does at call time beyond the schema's own note.

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 an explicit verb+resource+actor framing ('WRITE: send a chat message to a visitor as a Chatra agent') and names the sibling it is not (chatra_push_message). The side-effect marker ('WRITE') and the endpoint (POST /messages/) make it unambiguous against the read/edit/delete 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?

It states the selection condition ('only call it with text the user asked you to send') and an explicit negative case with a named alternative ('For automated notices ... use chatra_push_message instead'). No sibling routing is left to inference for the main confusion pair.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's real contribution is the partial-update contract: only passed fields change and `null` removes a value, plus that the updated visitor is returned. That meaningfully clarifies the destructive behavior declared in annotations, though it says nothing about auth or failure modes.

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

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

Three compact sentences, front-loaded with the WRITE marker, then the semantics, then the return/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?

Complete enough for a partial-update mutation: return value is noted despite no output schema, and annotations carry the safety profile. Missing only edge-case behavior (unknown client_id, validation failures), which keeps it off 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 coverage is 100%, so baseline is 3; the description earns a bump by stating the cross-parameter rule that only supplied fields are modified and `null` clears them, which the per-field schema descriptions imply but never state as a contract.

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 ('WRITE: edit a visitor's basic info') and enumerates the editable fields, so it is immediately distinguishable from the sibling message tools (chatra_edit_message, chatra_send_message) and from the read-only chatra_get_visitor.

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 'WRITE:' prefix and 'as if an agent edited it in the Chatra dashboard' framing imply this is the mutation path for visitor data, but there is no explicit 'use chatra_get_visitor to read first' or any when-not guidance. Usage is inferable rather than stated.

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