Zendesk MCP by usefulapi

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

Annotations only declare destructiveHint=true, so the description adds real value by stating it is a mutation and clarifying the default-visible-to-requester behavior of the `public` flag. It stops short of stating permanence, editability, or auth requirements for the mutation.

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 clauses, mutation warning front-loaded, then the one non-obvious parameter behavior. Every sentence earns its place with zero filler.

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

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

For a 3-parameter mutation tool with no output schema and full schema coverage, the description covers purpose, mutation nature, and the default-to-public behavior. Minor gaps remain around the response and whether comments can be altered after posting.

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 already documents id, body, and the public/internal-note semantics of `public`. The description's explanation of `public` largely repeats the schema, giving no additional format or constraint 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 ("add a comment to a ticket") plus an explicit MUTATING marker, which cleanly separates it from read siblings like zendesk_list_ticket_comments. It does not name a sibling or alternative directly, so it falls short of the 5 bar.

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 tells the agent how to use the `public` flag but gives no guidance on when to choose this tool versus alternatives such as zendesk_update_ticket or zendesk_create_ticket. Usage is implied by the verb, not 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?

The 'MUTATING' prefix broadly aligns with the destructiveHint=true annotation, and the description usefully notes that the comment becomes the ticket's first message. It does not disclose side effects an agent would care about for a create tool, e.g. that the requester may be emailed, that a ticket id is returned, or any permission requirements. No contradiction with 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?

Three very short sentences with the mutation warning and required fields front-loaded, followed by the endpoint. No filler and nothing buried.

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

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

With no output schema, the description omits what comes back from a create call (e.g. the new ticket id, useful for chaining to update_ticket). For a 10-parameter mutation tool this leaves side effects and return semantics to guesswork, though the parameter surface itself is well covered by the schema.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters including the two required ones. The description's restatement that subject and comment_body are required and that the comment is the first message largely duplicates the schema's own wording, adding only marginal semantic value.

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

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

States a specific verb and resource ('create a new support ticket') and the REST endpoint (POST /tickets.json), making the action unambiguous against siblings like zendesk_update_ticket or zendesk_add_ticket_comment. However, it never names or contrasts with those siblings, so it stops short of full differentiation.

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

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

There is no when-to-use / when-not-to-use guidance and no routing to alternatives (e.g. add_ticket_comment for an existing ticket). The only context is the 'MUTATING' prefix, which signals a write but does not tell the agent when this tool is the right 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, lowering the burden, and the description adds genuine context beyond that: it discloses the underlying REST call and what the result is good for (credential/subdomain verification). It doesn't describe the response payload shape, but for a zero-param whoami 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 sentences, front-loaded with the core action and followed by a one-clause rationale. No filler or redundancy.

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

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

For a trivial read-only, zero-parameter tool with no output schema, the description covers purpose, usage rationale, and endpoint — everything an agent needs to invoke it correctly. No meaningful gaps remain.

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 the schema has nothing to explain and the description correctly offers none. Baseline of 4 applies for a parameterless tool.

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 ('Return the currently authenticated user'), which cleanly distinguishes it from siblings like zendesk_get_user (by id) and zendesk_search_users. The endpoint reference (GET /users/me.json) reinforces the exact scope.

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

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

Gives a clear use context — 'a quick way to verify credentials and subdomain' — which tells the agent when this tool is the right pick rather than fetching a specific user. It does not explicitly name or exclude the sibling alternatives (e.g. zendesk_get_user), so it stops short of a 5.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context — it does so by naming the underlying REST endpoint (GET /views/{id}/execute.json) and confirming the return is matching tickets. It says nothing about pagination behavior, result caps, or view execution limits beyond what the schema's page/per_page params imply.

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

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

Two compact sentences, front-loaded with the action and outcome, with the endpoint mapping appended as an optional technical note. Nothing is redundant or padded.

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

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

For a single-resource read tool with a fully documented schema and no output schema, the definition covers what the tool does and roughly what it returns. The only mild gap is that it doesn't characterize the ticket payload or pagination envelope, though pagination params are visible in the schema.

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

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

Schema description coverage is 100%, so every parameter (id, page, sort_by, per_page, sort_order) is already documented in the schema; baseline is 3. The description adds only that the call is keyed 'by id', which the schema already states more precisely (numeric view id from zendesk_list_views).

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 ('Run a saved view by id') and states the outcome ('return the matching tickets'), which separates it from zendesk_list_views and zendesk_list_tickets. It doesn't name a sibling explicitly, so it stops short of a 5.

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

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

Usage is only implied: an agent infers this is the call to use when it has a view id and wants that view's tickets. There is no explicit when-to-use/when-not, no statement of prerequisites (e.g., that the view must exist or that list_views supplies the id — that hint lives only in the schema), and no alternative such as zendesk_search or zendesk_list_tickets is contrasted.

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 REST endpoint (GET /organizations/{id}.json), which is mild supplementary context, but says nothing about error behavior for a missing id or what the returned payload 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 short sentences, action first, endpoint reference second. No filler and nothing buried.

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

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

For a one-parameter read tool with readOnlyHint and full schema coverage, the definition supplies enough to call it correctly; no output schema exists, so return values need not be described. Only the usage routing against siblings is missing.

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

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

Schema description coverage is 100% and the single id parameter is fully documented in the schema, so baseline 3 applies. The description's 'by id' adds no syntax or meaning beyond what the schema already 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?

Specific verb (fetch) plus resource (a single organization) with the REST endpoint named. The word 'single' implicitly distinguishes it from the sibling zendesk_list_organizations, though it never names that sibling explicitly.

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

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

No statement of when to use this versus zendesk_list_organizations or zendesk_search. Usage is only inferable from 'by id', leaving the agent to guess the selection condition.

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's only added context is the REST endpoint mapping, which is minor for an agent; it says nothing about error behavior for missing/inaccessible ids or what ticket data is returned.

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, front-loaded sentences with no filler; the purpose leads and the endpoint reference trails as optional detail. Nothing in the text 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 single-parameter read tool with annotations covering safety and a fully documented schema, this is nearly sufficient. With no output schema, a brief note on what the ticket payload contains would have closed the remaining gap.

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

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

Schema coverage is 100% with a single integer parameter already documented as 'Numeric ticket id (required)'. The description merely restates 'by id' and adds no format, range, or lookup-strategy detail beyond the schema, 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 and resource ('Fetch a single ticket by id') and even names the underlying REST path, so the agent knows exactly what it retrieves. It does not explicitly differentiate itself from siblings such as zendesk_list_tickets or zendesk_get_ticket_metrics, which keeps it off a 5.

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

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

There is no when-to-use or when-not-to-use guidance. It never says whether to prefer this over zendesk_search or zendesk_list_tickets when the id is unknown, nor what prerequisites (auth, ticket visibility) apply. The 'by id' phrasing only weakly implies the condition.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context by naming the specific metric categories (SLA/response/resolution) and the REST path, but it does not describe return format, auth requirements, or rate limits beyond what annotations provide.

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 tightly written sentences with no wasted words, and the main purpose is front-loaded before the technical endpoint detail.

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

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

For a simple single-parameter read tool with no output schema, the description names the metric categories being fetched and the REST endpoint. It does not describe the return structure, but given the low complexity and the annotation-covered safety profile, it is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the single 'id' parameter is already fully documented as a required numeric ticket id. The description does not add syntax or format details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Fetch') and resource ('SLA / response / resolution time metrics for a ticket'), and it distinguishes itself from sibling tools like zendesk_get_ticket by focusing on metrics rather than ticket details. The REST endpoint notation further pins down the exact operation.

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 what the tool does but gives no when-to-use guidance, no conditions for choosing it over zendesk_get_ticket or other siblings, and no exclusions. The context 'for a ticket' implies a basic use case but does not constitute explicit usage guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying REST endpoint, which helps confirm the operation is a plain read, but says nothing about not-found/error behavior or any rate or auth constraints. Modest added value over 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, zero filler, and the core action is front-loaded before the endpoint reference. 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 trivial single-parameter read with readOnlyHint and full schema coverage, the definition is close to sufficient. It only lacks a note on the returned user object and failure mode, which is minor given no output schema exists.

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

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

Schema description coverage is 100% and the single 'id' parameter is fully documented in the schema. The description only restates 'by id' without adding format, sourcing, or id-resolution 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 and resource ('Fetch a single user by id') and grounds it in the Zendesk REST endpoint GET /users/{id}.json. An agent can distinguish it from search_users by the single-id scope, though no sibling is 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?

Usage is implied: fetch one user when you already hold a numeric id. It never states when to prefer zendesk_search_users or zendesk_current_user, which are the natural alternatives. No prerequisites or exclusions are given.

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 and the bar is lower. The description adds only the REST endpoint mapping (GET /groups.json), which is mildly useful for developers but says nothing about pagination behavior or result shape beyond what the params already imply.

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

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

Two short sentences, zero filler, with the core purpose front-loaded before the implementation detail. Nothing is redundant or padded.

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

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

For a simple, zero-required-parameter read-only list tool whose params are fully documented in the schema and whose safety profile is covered by annotations, the description is sufficient. Return format is unspecified, but no output schema exists, so a brief note on the returned group objects would be the only meaningful improvement.

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 page and per_page are already documented with types and limits. The description adds no parameter-level detail beyond the schema, which is the expected baseline 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?

States a specific verb and resource ('List agent groups') and even names the underlying REST endpoint, so the agent knows exactly what it retrieves. It does not differentiate itself from siblings, but no sibling covers groups, 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 offers no when-to-use, when-not-to-use, or alternative guidance. There is no indication of prerequisites, whether groups are needed before other calls (e.g., ticket assignment), or how this relates to zendesk_search_users or other listing tools.

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 structurally. The description adds the underlying REST endpoint (GET /macros.json), which tells the agent this is a straight passthrough to Zendesk's public API, but says nothing about pagination, page size, rate limits, or auth requirements.

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 no filler; the purpose statement leads and the endpoint reference is secondary. Nothing can be trimmed without losing information.

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

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

For a simple read-only list tool with full schema coverage this is close to adequate, but with no output schema the description should at least hint at the return shape or pagination behavior, and it does not. An agent knows what the tool is but not what comes back.

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 optional parameters (access, active) are already documented in the schema, including the 'personal'/'shared' example values. The description adds no additional parameter meaning, which is acceptable given the schema does the work.

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 (macros), and the parenthetical defines what a macro is for an agent that lacks Zendesk domain knowledge. It does not explicitly contrast itself with sibling list tools (list_views, list_groups), but the resource is unambiguous.

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

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

There is no when-to-use guidance, no mention of when to prefer zendesk_execute_view or search instead, and no prerequisites or caveats. The only usage signal is the implicit 'list macros' action itself.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the pagination mode ('offset pagination') and the underlying REST endpoint, which is mild but real context; however it says nothing about rate limits, default page size, total-count behavior, or auth requirements.

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, purpose first, pagination qualifier second, with no filler. The REST endpoint note is compact and useful to an API-aware agent rather than padding.

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

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

For a simple two-parameter read-only list tool with a fully documented schema and readOnlyHint annotations, the essentials are present. Still missing are the default/maximum effective page size behavior, whether the response includes pagination metadata, and how to narrow results — relevant since no filtering parameter exists.

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 'page' and 'per_page' are documented in the schema, including the max-100 bound and exclusive minimum. The description's '(offset pagination)' merely corroborates the page parameter and adds no format or default details beyond the schema, 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 and resource ('List organizations') and notes the pagination style, which cleanly separates it from the sibling zendesk_get_organization (singular) without needing to name it. It doesn't explicitly differentiate itself in text, but the verb/resource pair is unambiguous.

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

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

There is no when-to-use guidance, no mention of prerequisites or auth, and no routing to alternatives (e.g., zendesk_get_organization for a single org, or the fact that no org-search sibling exists). The agent must infer all usage context from the name alone.

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 REST endpoint (GET /satisfaction_ratings.json), which is mild extra context, but says nothing about pagination behavior or result volume beyond what the 'page' param already signals. Modest added value 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?

Two short sentences, zero filler, with the resource and the filtering capability front-loaded. Every clause earns its place.

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

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

For a read-only list tool with fully documented parameters, the description covers what it does and how it can be narrowed. No output schema exists, but the description indicates the return subject (CSAT ratings), leaving only minor gaps like default page size or ordering.

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

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

Schema description coverage is 100%, including the enum values for 'score' and the pagination semantics for 'page', so the schema does the heavy lifting. The description only restates that filtering by score is optional, adding no meaning beyond the structured fields. 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 ('List customer satisfaction (CSAT) ratings') and even gives the underlying REST endpoint, so the agent knows exactly what is returned. It is clearly distinguishable from siblings like list_tickets or list_views, though it does not explicitly name any sibling it must not be confused with.

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?

'optionally filtered by score' implies the main usage context, but there is no explicit when-to-use/when-not guidance or reference to an alternative tool. Adequate but leaves the agent to infer the scenario.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds real value beyond that by disclosing the sort order (oldest first) and that internal notes are included alongside public replies. It does not describe pagination behavior or response shape, so it stays at a solid 3.

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

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

Two tight sentences with zero filler; the scope (public replies and internal notes) and ordering are front-loaded before the endpoint reference. Every clause earns its place.

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

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

For a simple read-only listing tool with 100% schema coverage and a safety annotation, the description covers purpose, content scope, and ordering. The only minor gap is that, with no output schema, it could say more about the returned comment fields or pagination semantics.

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 id, page, and per_page are already fully documented in the schema. The description only reiterates that comments belong to a ticket, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (List) and resource (comments on a ticket) and clarifies the content scope: public replies and internal notes. It also names the underlying REST endpoint, so the agent can map it precisely. It does not explicitly distinguish itself from zendesk_add_ticket_comment, but the read/write split is obvious from the verb.

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: fetch the comment thread for a given ticket id. There is no explicit when-to-use, when-not, or alternative for the paginated retrieval case (e.g., a search or extended listing tool). Adequate but with clear gaps.

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

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

The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful scope (standard AND custom fields) and the underlying REST endpoint, but says nothing about pagination or result volume, which matters for a list endpoint. Adequate but not rich.

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

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

Two compact statements: purpose and rationale are front-loaded, and the REST endpoint is appended as a low-cost technical footnote. Every clause earns its place with no redundancy.

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

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

For a zero-param read-only list tool with no output schema, the description conveys what is returned (standard and custom fields) and why an agent would call it. Only pagination/result-size behavior is left unstated, a minor gap 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 tool takes zero parameters, so per the rubric the baseline is 4; there is nothing for the description to disambiguate. The description correctly implies this is an unfiltered full listing, which is consistent with the empty schema.

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

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

States a specific verb and resource ('List all standard and custom ticket fields') and qualifies the scope by naming the two field categories. An agent can distinguish it from siblings like zendesk_list_tickets or zendesk_list_ticket_comments 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?

Gives a concrete when-to-use rationale: discovering field ids/values before creating or updating tickets, which routes the agent correctly relative to zendesk_create_ticket and zendesk_update_ticket. It does not name explicit alternatives or exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context by disclosing the pagination model (offset) and the upstream REST call, but says nothing about rate limits, default page size, or result caps.

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, front-loaded with the action and scope. The REST endpoint note is arguably redundant given the schema, but it costs almost nothing and adds no clutter.

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

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

For a simple read-only list tool with fully documented parameters and no output schema, the description covers what an agent needs to invoke it correctly. Only the lack of guidance relative to sibling list/search tools keeps it from being fully complete.

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

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

Schema description coverage is 100%, and each of the four parameters (page, per_page, sort_by, sort_order) is documented in the schema itself. The description only echoes the pagination concept, adding no syntax or format detail beyond the structured 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?

States a specific verb and resource (list tickets) and adds scope detail (recent, offset pagination) plus the underlying REST endpoint. It does not distinguish itself from siblings like zendesk_search or zendesk_execute_view, which could also return tickets, so it stops short of a 5.

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

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

There is no explicit when-to-use guidance and no mention of alternatives such as zendesk_search for filtered queries or zendesk_get_ticket for a single ticket. The word 'recent' hints at scope but leaves the agent to infer when this tool beats its 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 readOnlyHint=true, so safety is covered by structured data rather than the description. The description adds only the underlying REST endpoint (GET /views.json), which signals a thin API proxy but says nothing about pagination, result limits, or auth requirements. Adequate given annotation coverage, but not rich.

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

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

Three short sentences, zero filler, with the purpose front-loaded before the alternative and the API reference. Every clause earns its place.

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

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

With no output schema, the description does not describe the returned view records (ids, names, counts) that an agent would need to feed into zendesk_execute_view. The pointer to the sibling mitigates this, but the return shape remains implicit 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% and both optional filters (access enum, active boolean) are documented inline, so the schema carries the load. The description adds no format or defaulting nuance, which is the expected baseline when the schema is complete.

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

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

States a specific verb and resource ('List saved ticket views') and immediately defines the domain term with a parenthetical ('curated ticket lists'). It also names the complementary sibling, so an agent can separate this discovery tool from zendesk_execute_view without opening either schema.

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

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

Explicitly routes the run-a-view case to zendesk_execute_view, giving a clear this-tool/then-that-tool pairing. It stops short of stating when listing views is unnecessary (e.g. when the view id is already known) or how this differs from zendesk_list_tickets, so it is strong but not exhaustive.

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 REST call (GET /search.json), which is minor context, but says nothing about result shape, pagination behavior (despite a page parameter), or rate limits. With annotations carrying the safety burden, this is adequate rather than rich.

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

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

Two tightly packed sentences: scope first, then concrete syntax examples, then the endpoint reference. No filler, and the most important information (what it searches and how to phrase the query) 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?

With no output schema, the description should ideally say something about what a result looks like or how pagination behaves (a page parameter exists and is undocumented behaviorally). Safety is covered by annotations and query construction is well covered, but the return/paging side is left entirely 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%, so the baseline is 3 and the schema already documents query, page, sort_by and sort_order. The description adds value by demonstrating multi-type query syntax (`type:user email:...`, `type:organization name:...`) beyond the single ticket example in the schema, clarifying how the required query parameter is constructed for non-ticket entities.

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

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

States a specific verb (search) and resource scope (tickets, users, organizations, groups) with the mechanism named (Zendesk search syntax). It is clearly distinguishable from narrow siblings like zendesk_search_users (users only) or zendesk_list_tickets (no query syntax), so an agent can route 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 'unified search' framing implies when this cross-entity tool is preferable to the single-entity list/search siblings, and the examples show realistic query contexts. However, there is no explicit when-to-use or when-not-to-use guidance versus zendesk_search_users or zendesk_list_tickets, leaving selection 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?

The annotation readOnlyHint=true already establishes this as a safe read operation. The description adds the underlying REST endpoint (GET /users/search.json), which reinforces that it is a read, but it does not disclose pagination behavior, result limits, rate limits, or authentication requirements beyond what the schema and annotations already convey.

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

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

Two short sentences with no wasted words. The primary purpose is front-loaded, followed by a compact technical reference, making it easy to scan.

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 low-complexity read-only search tool with 100% schema coverage and a readOnly annotation, the description is nearly complete. It omits only minor search semantics (e.g., whether matching is partial or exact, and how pagination interacts with total results), but the schema covers pagination parameters adequately.

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 the 'query', 'page', and 'per_page' parameters with examples and constraints. The description's mention of name/email/phone attributes maps to the query parameter but adds no syntax or format details beyond what the schema provides; the 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 ('Find') and resource ('users') and names the searchable fields ('name, email, phone, or other attributes'), making the tool's function clear. However, it does not explicitly distinguish this search-by-attribute tool from the sibling 'zendesk_get_user' (which fetches by ID) or the broader 'zendesk_search', so it falls short of full sibling differentiation.

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

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

The description only says what the tool does; it gives no guidance on when to use it versus alternatives like 'zendesk_get_user' or 'zendesk_search'. There are no exclusions or prerequisites stated, so the agent must infer usage from the tool name alone.

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 carry destructiveHint=true, and the 'MUTATING' label reinforces rather than contradicts that. The description adds the Zendesk REST endpoint (PUT /tickets/{id}.json), but says nothing about reversibility, permission requirements, or what happens to fields omitted from the payload — a meaningful gap for a destructive write 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?

Two compact sentences: the mutating nature is front-loaded, the required-input rule follows, and the REST endpoint anchors the call. No sentence is filler.

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

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

With 9 mostly-optional parameters at full schema coverage and a destructiveHint annotation, the description covers the essentials: the required id, the at-least-one-field rule, and the mutation semantics. It omits return-value expectations (no output schema exists) and the partial-update behavior of omitted fields, so it is strong but not fully complete.

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

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

Schema description coverage is 100%, so every parameter including the comment_public default is already documented in the schema. The description's field list slightly overlaps the schema but adds no syntax, format, or interaction guidance beyond it, 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?

Names a specific verb and resource ('update an existing ticket') and prefixes it with 'MUTATING', which cleanly separates it from the read siblings (zendesk_get_ticket) and from zendesk_create_ticket. The enumeration of updatable fields makes the scope concrete rather than tautological.

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

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

States a clear precondition ('Provide the ticket id plus at least one field to change') and lists the acceptable fields, which tells the agent how to form a valid call. It does not, however, tell the agent when to prefer a sibling such as zendesk_add_ticket_comment or when not to use this tool.

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