SupportBee MCP by usefulapi

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

Annotations only supply destructiveHint=true, whose basis is unexplained for what is conceptually an additive write; the description adds substantive context beyond that by disclosing visibility scope (agents only), the non-notification behavior (never e-mailed), and the underlying endpoint. It does not explain the destructive flag or auth/rate-limit 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?

Three tight sentences, front-loaded with the 'WRITE:' marker so the mutation nature is instantly visible, then the key behavioral qualifier, then the endpoint. Nothing is wasted.

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 write tool with no output schema, the description covers purpose, visibility, notification behavior, and endpoint. Missing only ancillary detail such as error behavior for invalid ticket ids, which is minor.

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

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

Schema description coverage is 100%, so both parameters (text, ticket_id) are already fully documented in the schema. The description only adds the endpoint shape POST /tickets/{id}/comments, which lightly clarifies how ticket_id is consumed, 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 (adds) and resource (an internal comment on a ticket), and immediately qualifies the comment type as internal/agent-only. This cleanly distinguishes it from the emailing sibling supportbee_reply_to_ticket.

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?

Conveys when to use it by defining the semantics: comments are agent-visible only and never e-mailed to the customer, which implies the correct choice versus reply_to_ticket. It stops short of explicitly naming that alternative or any 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?

Adds real context beyond the annotations: a 404 if the label does not exist, the label-source prerequisite, and the underlying POST endpoint. 'Safe to repeat' largely restates idempotentHint=true, but the error behavior is information the annotations do not carry.

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

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

A single front-loaded sentence with the WRITE marker first, then semantics, failure mode, dependency, and 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 simple two-parameter write with no output schema and idempotency already annotated, the description covers purpose, prerequisite, failure mode, and endpoint. Nothing essential is missing, though a note on the response/effect would round it out.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the label-name source. The description only echoes that label names come from supportbee_list_labels, adding no new syntax or format detail beyond the schema baseline.

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

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

States a specific verb and resource ('adds an existing label to a ticket') and the wiring to the sibling that supplies valid labels (supportbee_list_labels). This cleanly distinguishes it from supportbee_remove_label and the other ticket-mutation siblings.

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

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

Explicitly frames the operation as a WRITE and directs the agent to supportbee_list_labels for valid names, which is the prerequisite an agent needs. It does not state when *not* to use it, but the 'existing label' constraint effectively scopes usage.

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 cover idempotency and non-destructiveness; the description adds real behavioral context beyond that — the user assignee is silently removed when reassigning to another team, the customer is not e-mailed, and the assigned agent may be notified. It also discloses the underlying endpoints, so the agent understands the exact side effects.

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 mutation class front-loaded and the XOR rule stated before the edge cases. The trailing 'POST /tickets/{id}/...' endpoint detail is implementation-level and adds little for an agent, costing a point.

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

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

For a 3-parameter write tool with no output schema, it covers targets, side effects, notifications, and the team-membership prerequisite. It does not mention what a failed assignment returns (e.g., a non-member user) or the response shape, though that 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 coverage is 100%, so the baseline is 3, but the description goes further by defining the mutual exclusivity of user_id/team_id (a constraint the schema does not encode) and the rule that a team assignee must already be a member. It stops short of stating that ticket_id is mandatory and that omitting both targets fails.

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?

It names a specific verb (assigns) and resource (ticket) and immediately states the two mutually exclusive targets (user_id XOR team_id). 'WRITE:' front-loads the mutation class, making it clearly distinct from sibling supportbee_unassign_ticket and the read 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?

It gives explicit routing context: choose exactly one of user_id or team_id, and only a team member can receive a team-owned ticket. It does not, however, explicitly name when to prefer this over supportbee_unassign_ticket or the conditions under which assignment should be skipped.

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 value by naming the returned fields and the underlying GET endpoint, but says nothing about failure modes (e.g., reply/ticket not found) or permission requirements. Adequate but thin on behavior 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 short sentences, front-loaded with the resource and its contents before the endpoint detail. Nothing is wasted, though the raw endpoint string earns only marginal value for an agent.

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 single-item fetch with 2 fully documented params, the description covers the resource and key return fields even without an output schema. It still omits behavior on missing/unauthorized replies, leaving a modest 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%, with reply_id and ticket_id each documented including their provenance tools, so the schema carries parameter meaning. The description adds no parameter-level detail (no format, range, or scoping notes), 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?

The description states a specific verb+resource: fetching one reply of a ticket, and names the returned fields (text, replier, cc/bcc) plus the exact HTTP route. It implicitly distinguishes itself from supportbee_list_replies by the singular scope, though it never names that sibling as an alternative.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as supportbee_list_replies. Usage must be inferred from the singular 'one reply' phrasing and the schema's pointer to supportbee_list_replies.

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?

With only readOnlyHint available, the description carries meaningful extra weight: it discloses the admin-token authorization requirement, the underlying endpoint (GET /reports/{report}), and the return shape as time-series data points. What it does not cover – pagination, date-range defaults, or granularity of the series – keeps it from a 5.

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

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

One dense, front-loaded sentence plus a compact endpoint reference; nothing is padded. It is slightly over-packed (report types, filters, auth, and route in one breath), but every clause carries information.

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

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

For a read-only, no-output-schema tool, the description supplies the essentials: what is returned, its point structure, the available scoping filters, the report enum values, and the auth requirement. Only secondary details like time-series granularity or default date range are absent.

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

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

Schema description coverage is 100%, so the schema already documents user, team, label, since and the report enum. The description only restates that one agent/team/label may be selected, adding no syntax or format detail (e.g. how `since` interacts with windowing). 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?

The description names the exact resource (a report), the three concrete report types it can return (tickets_count, replies_count, avg_first_response_time), and its output shape (value/timestamp pairs). It is unambiguous, though the action verb is left implicit (inherited from the title) rather than stated, and there are no sibling report tools to differentiate from.

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 a real precondition ("Needs an admin token") and that filtering by agent, team or label is optional, which tells the agent how it may be scoped. There is no when-to-use/when-not guidance or any named alternative, so usage context is implied rather than 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?

readOnlyHint=true already establishes this as a safe read, so the bar is lower. The description adds useful scope detail: it returns only the first message text and excludes replies/comments. It does not cover pagination, auth requirements, or error behavior for a missing ticket id.

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, zero filler. The returned-field list comes first, then the scoping exclusion, then the endpoint hint — well front-loaded and every sentence earns its place.

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

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

There is no output schema, so the description carries the burden of describing the return value, and it does so concretely (fields plus the first message text only). For a simple single-read tool this is nearly complete; only error/not-found behavior 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?

With one parameter at 100% schema coverage, the schema already fully documents ticket_id (including provenance from supportbee_list_tickets). The description's 'GET /tickets/{id}' only echoes the single-id shape without adding format or edge-case guidance, 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/resource pair implicitly ('one ticket') and enumerates the returned fields (subject, requester, labels, assignees, state, first message text). It also distinguishes itself from siblings by noting replies and comments are separate calls, so an agent can tell it apart from get_reply/list_comments without opening schemas.

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

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

The sentence 'Replies and comments are separate calls' routes the agent away from expecting threaded content and implicitly toward get_reply/list_comments/list_replies. It gives clear context but does not explicitly name those alternatives or state when-not-to-use conditions.

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?

With readOnlyHint=true already declaring the operation safe, the description adds useful behavioral content: it enumerates what the audit trail contains (assignments, label changes, replies, archiving) and that entries carry timestamps. It does not cover pagination, ordering, or result size, which keeps it short of a 5.

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

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

One dense sentence states the payload and its contents, followed by the endpoint path. Nothing is repeated or padded, and the core purpose is front-loaded.

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

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

For a single-parameter, read-only tool with no output schema, the description gives an agent enough to call it correctly and anticipate event entries with timestamps. It stops short of describing ordering or completeness of the trail, which would round out the picture.

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

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

Schema description coverage is 100% for the single required ticket_id, and that schema description is richer than the tool description (it explains the id is the number in the ticket URL and points to supportbee_list_tickets). The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

The description states a specific resource and payload: the audit trail of a ticket, enumerating the event types (assignments, label changes, replies, archiving) and noting timestamps. It separates itself conceptually from supportbee_get_ticket (current state) by framing the tool as historical events, though it does not name 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?

Usage is only implied: 'what happened to a ticket' suggests a historical/investigative lookup, but there is no explicit statement of when to call this versus supportbee_get_ticket or supportbee_get_report, and no prerequisites are mentioned. An agent can infer intent but gets no 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds value by disclosing the returned payload shape (role, teams, ticket counts, recent tickets), which matters because no output schema exists, but it says nothing about auth requirements, error behavior, or pagination.

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 fragments with no filler. It front-loads the resource payload and appends the endpoint, though the leading noun phrase is a sentence fragment rather than a verb-led statement.

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

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

For a two-parameter read with full schema coverage and read-only annotations, the description is adequate but thin: no output schema exists, yet the return content is only sketched, and there is no guidance on usage or selection among the many sibling get_* tools.

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

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

Schema description coverage is 100%, including where user_id comes from and what max_tickets controls, so the schema carries the parameter burden. The description only loosely alludes to max_tickets via 'a few of their recent tickets' and adds no format or constraint detail.

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

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

The description states a specific resource and its payload — 'One user or customer with role, teams, ticket counts and a few of their recent tickets' — which tells the agent exactly what is fetched, and 'GET /users/{id}' anchors it to a single-resource read. It does not explicitly name list_users as the sibling alternative, but the singular framing makes the distinction 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?

There is no when-to-use guidance, no statement of prerequisites, and no mention of the alternative list_users for bulk retrieval. The only routing hint ('from supportbee_list_users') lives in the input schema, not the description.

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?

With readOnlyHint=true already covering the safety profile, the description adds real context: comments are visible to agents only, are never e-mailed, and come back ordered oldest-first as text. It stops short of mentioning pagination or volume limits, but it clears the bar set by the annotations.

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

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

One sentence plus the endpoint, zero filler. The discriminating qualifier (agent-only, never e-mailed) is front-loaded before the ordering and format details.

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 no output schema, the description usefully states the return shape (text) and ordering (oldest first), which the agent otherwise could not know. It could go slightly further on result size or pagination, but nothing essential 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%; the ticket_id parameter is fully documented in the schema (source URL, originating tool) and the description adds nothing further. This matches the baseline of 3 when the schema does the heavy lifting.

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

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

Names a specific resource and scope: internal (agent-only, never-e-mailed) comments on a single ticket, plus the underlying endpoint. The parenthetical distinguishing internal comments from e-mailed content implicitly separates it from supportbee_list_replies, though it never names that sibling directly.

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 domain framing (internal vs. external comment) rather than stated. There is no explicit 'use this when...' clause, no prerequisites, and no contrast with supportbee_get_reply or supportbee_list_replies, so the agent must infer the choice.

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 real value by disclosing the return payload fields (id, name, arrival address, from address) — notable because there is no output schema. It doesn't mention pagination or ordering, but for a small desk-level list that is minor.

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 sentence fragments with the resource named first and the returned fields enumerated second; the trailing 'GET /emails' is slightly redundant. Nothing is padded, though the telegraphic style reads as notes rather than prose.

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 no-argument, read-only listing tool with no output schema, the description supplies the essential missing piece — what each returned record contains. An agent has enough to call it and interpret results.

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 no parameters, so schema coverage is trivially 100% and the baseline of 4 applies. There is no parameter meaning for the description to add or omit.

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 resource (the desk's support/forwarding e-mail addresses) and enumerates the fields returned. The purpose is unambiguous, though it doesn't need sibling differentiation since no other list tool targets forwarding addresses.

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: an agent can infer this is the way to discover which addresses tickets arrive at. There is no explicit when-to-use note or named alternative, but for a zero-argument read-only listing tool little guidance is required.

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 by structured data. The description adds that the payload contains only name and color, but says nothing about ordering, volume, or pagination for what could be a long label list.

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

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

Three terse fragments with the scope statement front-loaded and no filler. The trailing 'GET /labels' endpoint note is marginally redundant but cheap and useful for API mapping.

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-param, read-only list tool with no output schema, the description supplies the essential missing piece — what fields are returned — and points at the consumer tool. It stops short of describing ordering or size characteristics.

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 the baseline is 4. There is nothing for the description to disambiguate and it correctly makes no false claims about filtering options.

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 labels') and enumerates exactly what comes back ('name and color'), which distinguishes it from sibling list tools such as supportbee_list_users or supportbee_list_teams.

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 routes the agent explicitly: use the returned label name with supportbee_add_label or with the label filter. That is clear context and a named downstream consumer, though it never states when this tool should not be used (e.g. a lookup by name alternative does not exist 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?

With readOnlyHint already declaring safety, the description adds useful behavioral detail: the replies are public, returned oldest first, and formatted as text. It does not mention pagination or rate limits, but it goes beyond the annotation by specifying ordering and output format.

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 two compact sentences with no filler, front-loading the resource and scope before the endpoint. Every element—public scope, ordering, format, endpoint—adds value.

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 one-parameter list tool with readOnlyHint and full schema description coverage, the description covers what is returned, ordering, and public scope. It omits pagination or result limits, which is a minor gap but not disqualifying given the tool's simplicity.

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 schema fully documents the single ticket_id parameter, including its origin from supportbee_list_tickets and URL context. The description adds no additional parameter meaning beyond the endpoint path, so the baseline 3 for high schema coverage applies.

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

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

The description identifies the resource precisely as the public replies (customer conversation) of a ticket and adds scope details like 'oldest first' and 'as text'. It implicitly separates this from list_comments by emphasizing public customer conversation, but does not explicitly name siblings. A clear, specific retrieval tool, though the verb is carried by the title/name rather than 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?

No explicit when-to-use or when-not-to-use guidance is given, and no alternative tools are named. The parenthetical '(the conversation with the customer)' implies this is for public customer replies rather than internal comments, which gives some usage context, but the agent must infer when to prefer it over supportbee_list_comments or supportbee_get_reply.

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 tells the agent this is a safe read, so the description does not need to re-establish that. It adds some value by naming the returned fields (name, tags, text), but discloses nothing about ordering, pagination, or whether snippets are scoped to the company versus a user. Moderate context on top of annotations.

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

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

A single tight sentence with no filler, front-loading the resource and its fields. The trailing 'GET /snippets' is mildly redundant with the tool name but still useful as an endpoint indicator.

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 list tool with no output schema, the description is nearly sufficient: it names the resource and the fields returned. It omits ordering/pagination and the sibling distinction, but nothing critical to invoking the tool correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond what the empty schema already conveys.

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 the specific resource (canned replies/snippets of the company) and clarifies the terminology with 'snippets', then enumerates the fields returned (name, tags, text) plus the purpose ('to reuse in a reply'). It does not explicitly distinguish itself from the neighboring supportbee_list_replies, which is a plausible source of confusion for an agent, so it falls short of 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?

Usage is only implied: 'to reuse in a reply' suggests the agent fetches snippets when composing a canned answer, but there is no explicit when-to-use statement nor any exclusion or routing to supportbee_list_replies, which sounds similar but serves a different purpose. Adequate but with a clear gap.

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 the endpoint (GET /teams) and confirms the returned shape is limited to id and name, but says nothing about pagination, ordering, or empty-result 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?

A single compact sentence that front-loads the resource and then the optional scoping, with no filler. Slightly dense phrasing but nothing wasted.

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 no output schema, the description supplies the resource, returned fields, and filtering modes. Nothing critical for calling it correctly is missing; only pagination/ordering details are absent.

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

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

Schema description coverage is 100%, so both boolean filters are already fully documented, including the note that with_users does not add the member list. The description restates the same filters without adding format or interaction semantics, so baseline 3 is correct.

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 (teams of the company), and names the returned fields (id, name), so an agent knows exactly what comes back. It stops short of naming how it differs from any sibling, though no sibling lists teams, so the risk of confusion is low.

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

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

The description explains the two optional scoping modes (teams with users, token user's teams), which implies when each filter applies, but gives no explicit when-to-use guidance or exclusions relative to alternatives. 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.

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 value beyond that: default exclusion of archived/spam/trash tickets, the field set of each returned ticket, and the special total_only response mode, which an agent could not get from the annotations alone.

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?

Five compact sentences, front-loaded with the core verb and scope, then defaults, then return shape, then the total_only special case. Dense but every clause carries information; only the trailing 'GET /tickets' is arguably redundant for an agent.

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 fields present on each ticket and explains the total_only variant, covering the main return-shape gap. Pagination semantics (page/per_page) are only in the schema, but the description is otherwise complete for a list tool.

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

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

Schema description coverage is 100%, so all 15 parameters are already documented at the schema level. The description restates the filter categories and total_only but adds no syntax, precedence, or interaction detail beyond what the schema provides, making the baseline 3 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+resource ('List tickets of the shared inbox') plus default ordering and a summary of the filter set. It is clear and self-contained, but it never distinguishes itself from the sibling supportbee_search_tickets, so an agent must infer the boundary.

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?

Default filtering behavior is disclosed ('By default archived, spam and trashed tickets are left out'), which is useful context. However, there is no explicit when-to-use guidance or mention of when to prefer supportbee_search_tickets over this tool, leaving usage to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /users) and the shape of returned records, but says nothing about pagination, result size, or rate limits — modest added context, not rich behavioral disclosure.

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?

Compact and front-loaded: the resource comes first, then the practical hint, then the endpoint. Slightly elliptical phrasing (a bare noun phrase plus fragment) but nothing wasted.

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 list tool with full schema coverage and no output schema, the description covers what entities are returned, their fields, and how to reuse the id downstream. Only pagination/result-limit behavior is unaddressed, 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%, so type, with_roles and with_invited are fully documented in the schema — baseline 3 applies. The description's "or customer groups" restates the type enum rather than adding filtering syntax or defaults 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?

Names the resource precisely (agents/admins/collaborators or customer groups) and enumerates the returned fields, so an agent knows what comes back. It omits an explicit verb and does not name the nearest sibling, supportbee_get_user, which is the single-record counterpart — so sibling discrimination is only implied.

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 the id as assigned_user or user_id" tells the agent why the result matters (feeding IDs into assignment calls), which implies a usage context. However there is no explicit when-to-use statement and no comparison against supportbee_get_user for fetching a single user.

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

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

Beyond the annotations (idempotentHint=true, destructiveHint=false), the description explicitly labels this as a 'WRITE' and discloses the error contract: the label resource survives and a missing association returns 404. It does not describe the response payload, but the added behavioral detail is real and specific.

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 parentheticals plus an endpoint, with the mutation type front-loaded as 'WRITE:' so an agent can triage risk at a glance. No sentence is redundant.

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

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

For a two-parameter write with no output schema, the description covers the operation, the endpoint, and the failure mode, which is enough to invoke correctly. Only the success response shape is absent, which is a minor gap for a delete-style call.

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 ticket_id and label are already documented in the schema, including where ticket_id comes from. The description echoes the path shape 'DELETE /tickets/{id}/labels/{label}' but adds no new meaning about either parameter. 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 ('removes a label from a ticket') and immediately disambiguates from the mutating-the-label interpretation with '(the label itself stays)'. This lets an agent distinguish it from supportbee_add_label and supportbee_list_labels 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?

The description gives one useful precondition ('404 if the ticket does not have it'), which tells the agent what happens on a no-op call, but it never names the sibling alternative (supportbee_add_label) or states when to prefer this tool. Usage is implied rather than directed.

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

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

Annotations only provide destructiveHint=true; the description adds critical context beyond that: it sends an e-mail to the requester and cc/bcc, cannot be recalled, comes from the token's user, and caps recipients at 10. These are exactly the behavioral traits that aren't in structured data.

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: SENDS AN E-MAIL' in caps to signal the operation type immediately, then layers the alternative and the endpoint. Every sentence earns its place 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?

Complete for a write tool: it covers what happens (e-mail sent), recipients, irreversibility, sender identity, and the alternative for internal notes. No output schema needed since it returns a simple POST result. Nothing critical is missing.

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

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

Schema coverage is 100%, so all four parameters are documented in the schema, including the cc+bcc<=10 constraint. The description reinforces the address cap but adds no syntax or format detail 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 (reply) and resource (ticket), specifies it posts a public reply on ONE ticket, and explicitly distinguishes from sibling supportbee_add_comment (internal note). An agent can immediately tell this apart from related 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?

Explicitly names the alternative (supportbee_add_comment) and the condition that selects it ('For a note only your team sees'). Clearly frames this as the public/customer-facing option.

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=true, so the description usefully adds the default result ordering (newest activity first), the default exclusion of spam and trash unless explicitly requested, and the backing endpoint GET /tickets/search. It does not contradict the read-only annotation, and the filtering defaults are exactly the kind of behavior an agent needs.

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 plus an endpoint reference, with the scoping statement (full-text search over specific fields) front-loaded before the ordering and exclusion defaults. No filler or restated title content.

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 search tool with no output schema, the description covers scope, ordering, default exclusions, and the endpoint; pagination is fully documented in the schema. Return shape is left implicit, which is the only 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 value the schema lacks: it flags that the query parameter uses SupportBee's dedicated search syntax, which the schema merely calls 'search keywords or query'. It also reinforces the spam/trash default semantics. The syntax itself is not explained, keeping this short of a 5.

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 (full-text search) and resource (tickets), names the searched fields (subject, body, requester), and specifies ordering (newest activity first). The 'search' verb clearly separates it from the sibling supportbee_list_tickets without needing to name it.

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 implies usage (full-text search with SupportBee's search syntax) and notes that spam/trash are excluded by default, but it never states when to prefer this over supportbee_list_tickets or supportbee_get_ticket. Usage is inferable but not spelled out.

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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: the 'WRITE:' marker, the no-notification side effect ('without sending anything'), and the underlying POST/DELETE endpoints. It does not, however, describe what the response contains, though no output schema exists.

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 sentence with the operation type front-loaded, the boolean semantics inlined as parentheticals, and the endpoint appended. 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 two-parameter boolean toggle with annotations covering idempotency and destructiveness, and no output schema required, the description is nearly sufficient. The only minor omission is any hint about the resulting ticket state or response confirmation.

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% – both parameters are already fully documented in the schema, including the boolean polarity and the ticket_id source. The description's 'answered=true / answered=false' restates the schema rather than adding syntax or format detail, 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 ('marks a ticket as answered') with the exact boolean polarity inlined, which is precisely what distinguishes it from siblings like supportbee_set_ticket_archived and supportbee_reply_to_ticket. An agent can select it without opening the schema.

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

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

'without sending anything' explicitly separates this from supportbee_reply_to_ticket and supportbee_add_comment, which is the main mis-selection risk for a ticket-state tool. It gives clear context for use but states no explicit 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 supply idempotentHint=true and destructiveHint=false, and the description adds meaningful context: it characterizes the operation as a WRITE, asserts 'Nothing is deleted or sent', and discloses the underlying POST/DELETE endpoint. This goes beyond the annotations, though it omits any return-value or error 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?

Three compact sentences with the operation type and primary effect front-loaded, followed by the crucial 'nothing is deleted' reassurance and the 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?

For a two-parameter boolean-toggle tool with full schema coverage and no output schema, the description covers purpose, both modes, safety profile, and endpoint—everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and the schema already documents both parameters, including the archived=true/false mapping. The description merely restates that mapping, so it earns the baseline for high-coverage schemas rather than adding new semantic detail.

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

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

States a specific verb and resource ('archives a ticket... or moves it back') and even labels the operation type ('WRITE'). An agent can distinguish this from sibling mutation tools like supportbee_assign_ticket or supportbee_add_label without opening the schema.

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

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

Explains the two directional modes clearly (archived=true leaves the open inbox, archived=false moves it back), which tells the agent when each value applies. It does not name an alternative tool for restoring tickets, but the mode semantics effectively cover the usage decision.

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 idempotentHint=true and destructiveHint=false, so the safety profile is partly covered; the description adds that this is a WRITE and that it hits a DELETE assignment endpoint, clarifying that only the assignment is cleared, not the ticket. It does not say whether the previous assignee is recoverable or what the response contains.

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

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

Two compact sentences with zero filler, and the operation type ('WRITE') is front-loaded. Every clause carries information.

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

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

For a 2-parameter, fully-required tool with complete schema coverage and no output schema, the description plus annotations supply enough to invoke it correctly. A note on reversibility or the post-clear ticket state would make it exhaustive.

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 documented in-schema, so the baseline is 3. The description restates the user/team distinction for the assignee parameter but adds no format or constraint detail beyond the enum already in the schema.

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

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

States a specific verb (clears) and resource (the user or team assignee of a ticket), and 'unassign' cleanly distinguishes it from the sibling supportbee_assign_ticket. An agent can tell exactly what happens without opening the schema.

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

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

The 'WRITE' marker and endpoint hints imply this is the mutation counterpart to supportbee_assign_ticket, and the assignee enum shows the two modes, but there is no explicit when-to-use/when-not or named alternative. 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.