zendesk

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

Annotations already have destructiveHint=true, and the description adds 'MUTATING' to reinforce the mutation. It also discloses the default behavior of `public` and the mapping to the REST API, which exceeds annotation coverage. No contradictions.

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

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

Two sentences, front-loaded with the operation, and uses compact phrasing that earns its place. No filler 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 3-parameter mutation tool with no output schema, the description covers purpose, public behavior, and API relationship. Missing return value or permission details, but annotations compensate for safety; adequate for the complexity.

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

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

Schema covers 100% of parameters with descriptions for id, body, and public. The description only restates the public default that's already in the schema, so it adds no new semantic value beyond structured data.

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?

Clearly states 'add a comment to a ticket' with a specific verb and resource. Distinguishes from sibling tools by clarifying the `public` flag and being a convenience wrapper over PUT /tickets/{id}.json, so it's not confused with update_ticket or create_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?

Provides context about the public flag default and internal note option, but doesn't explicitly name sibling tools or state when to prefer this over update_ticket/list_ticket_comments. The API convenience mention is implicit guidance but not a clear alternative.

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 include destructiveHint=true, and the description reinforces this with 'MUTATING'. It adds behavioral detail that the comment becomes the ticket's first message and specifies the REST endpoint. No contradiction; description adds value beyond the annotation.

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

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

The description is three short sentences, front-loaded with the main purpose. Every sentence earns its place: the MUTATING label, required fields, comment semantics, and REST endpoint. No redundant 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 full schema coverage and a simple create operation, the description covers essential usage context. It lacks return value details, but there is no output schema and the tool's behavior is fairly self-evident. The description is sufficient for an agent to select and invoke 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%, so the baseline is 3. The description only highlights that subject and comment_body are required, which is already in the schema, and adds the comment-to-first-message semantic. No additional parameter-level details 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?

The description clearly states 'create a new support ticket' with a specific verb and resource. It distinguishes from siblings like update_ticket and add_ticket_comment by noting the comment becomes the first message, which is unique to new ticket creation.

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 provides clear context that this tool is for creating new tickets and notes the required fields. It does not explicitly name alternatives or when-not-to-use, but the sibling list implies other operations for existing tickets, and the 'MUTATING' hint clarifies the action.

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 provide readOnlyHint=true; the description adds the REST endpoint (GET /users/me.json) and the practical use of verifying credentials and subdomain. This goes beyond the annotation without contradicting it.

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 concise sentences: the first states the action, the second gives the REST endpoint and use case. Every word earns its place; no redundancy or 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 zero-parameter, read-only 'whoami' tool, the description fully covers purpose, use case, and endpoint. The absence of an output schema is irrelevant since the operation is trivial and self-explanatory.

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 has zero parameters and the schema is empty, so the description correctly needs no parameter details. The 0-param baseline of 4 applies here.

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 'Return' with a clear resource 'the currently authenticated user,' immediately distinguishing it from sibling tools like get_user or search_users. The title 'whoami' further reinforces the self-referential 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?

It explicitly frames the tool as 'a quick way to verify credentials and subdomain,' giving clear guidance for when to use it (auth/session checks). While it doesn't explicitly name alternatives, the current-user scope is obvious among the sibling read 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 declare readOnlyHint=true, which covers the non-destructive nature. The description adds the REST endpoint but doesn't disclose pagination behavior, sort semantics, or response format; no contradictions.

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 a single concise sentence that front-loads the action and result, followed by a useful endpoint reference. Every element earns its place.

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

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

For a read-only operation with an output described as 'matching tickets,' the description is reasonably complete. It includes the REST endpoint and the outcome, while the schema covers parameter details. Lacking an output schema, it could mention response structure, but this 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?

All parameters have schema descriptions, so the schema carries the meaning. The description adds only the context that the id refers to a view, which the schema already says ('view id'). No additional 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?

The description uses a specific verb ('Run'), a clear resource ('a saved view'), and an outcome ('return the matching tickets'). It also provides the exact REST endpoint, distinguishing it from sibling tools like zendesk_list_views and zendesk_search.

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 lacks guidance on when to choose this tool over alternatives like search or list_tickets. It only implies usage by naming the operation, and the id schema references list_views as a prerequisite.

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 readOnlyHint annotation already declares the safe read nature. The description adds the REST endpoint but no further behavioral details such as response format or error handling. With annotations covering safety, this is 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?

The description is two short sentences, front-loaded with the core action, and includes the endpoint reference without any waste. Every word earns its place.

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

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

For a single-parameter read tool, the description is sufficiently complete. It states what is fetched and the endpoint. The lack of an output schema is mitigated by the clarity of 'Fetch a single organization.' Minor gaps like error handling are not critical here.

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 provides 100% coverage with a clear description for the id parameter. The tool description adds no additional parameter semantics, 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 'Fetch a single organization by id' uses a specific verb and resource, clearly distinguishing it from sibling tools like get_user or list_organizations. It exactly states the tool's scope and function.

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

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

The description clearly indicates this is for retrieving a single organization by id, implying when to use it. It does not explicitly mention alternatives like list_organizations, but the context is unambiguous enough for a simple fetch operation.

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 known. The description adds the REST GET method and the endpoint, but no deeper behavioral details 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 concise sentences with no filler; front-loaded with the core action and resource.

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 fetch tool with read-only annotation, the description sufficiently covers purpose and endpoint. It does not describe the response format, but the absence of an output schema and the simplicity of the operation make this acceptable.

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

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

Schema coverage is 100% for the id parameter, and the schema already describes it as a numeric ticket id. The description's REST path confirms the id's role as a path parameter, adding minimal extra meaning.

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'), names the resource ('single ticket by id'), and includes the REST endpoint, clearly distinguishing it from sibling tools like list_tickets or get_ticket_metrics.

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

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

The description clearly indicates the use case (fetch one ticket by id) but does not explicitly contrast it with alternatives like list_tickets. It provides clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, and the description adds the specific metric types and REST endpoint, but doesn't describe response format or rate limits.

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

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

Two concise sentences, front-loaded with purpose, followed by API reference. 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?

Given one parameter and read-only annotation, the description covers the operation sufficiently, though it could specify the response shape. Slightly above minimum.

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 only parameter 'id' is fully described in the schema with type and constraints, so the description adds no new parameter semantics; 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 clearly states the tool fetches SLA/response/resolution metrics for a ticket, and the REST endpoint disambiguates from siblings like zendesk_get_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?

No explicit alternatives are mentioned, but the focus on metrics makes its use case clear: when ticket metric details are needed. Context is clear but lacks explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, covering the read-only nature. The description adds the REST endpoint (GET /users/{id}.json), which is mild context. However, it does not disclose error behavior, authentication requirements, or other behavioral traits, so it adds limited value beyond the annotation.

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

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

The description is a single, focused sentence that states what the tool does and the API endpoint. There is no wasted wording, and it is immediately clear and 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 tool with one parameter, no output schema, and a readOnlyHint annotation, the description is sufficient. It clearly identifies the resource and operation; the context needed to invoke it correctly is fully covered by the schema and annotation.

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 input schema provides 100% coverage for the only parameter 'id', including its type and description. The description merely repeats 'by id' and adds no additional semantic meaning, so it does not elevate the baseline for high schema coverage.

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 clearly states the tool fetches a single user by id, using the specific verb 'Fetch' and resource 'user'. It distinguishes this from sibling get_* tools by specifying the exact target (user vs organization, ticket, etc.), and also provides the REST endpoint for precision.

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 for retrieving a specific user's details by id, but it does not explicitly state when to use this tool versus alternatives like zendesk_current_user or zendesk_search_users. No exclusions or alternative guidance are provided, making the usage context merely implicit.

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 readOnlyHint annotation already signals a safe read operation, and the description aligns by using 'List'. The description adds the REST endpoint, which is minor context, but does not disclose potential pagination limits, response structure, or rate-limit behavior. This is a minimal but non-contradictory addition.

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 short sentences, immediately states the purpose, and includes the REST endpoint without any fluff. It earns its place with 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 list tool with read-only annotation, pagination schema, and no nested objects, the description is nearly sufficient. It lacks explicit mention of the return format (list of groups), but that is implied by the tool name and purpose. The endpoint reference adds useful technical context.

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

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

Schema coverage is 100% with both page and per_page documented in detail, so the description does not need to explain parameters. The description itself adds no parameter-specific meaning, which is appropriate given the schema's completeness.

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 clearly states 'List agent groups' with a specific verb and resource, distinguishing it from sibling tools like list_macros or list_tickets. The REST endpoint reference further confirms the intended action.

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 guidance is provided on when to use this tool versus alternatives. There is no mention of scenarios where listing groups is appropriate or any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, and the description adds context by defining macros and citing the REST endpoint. However, it does not disclose pagination behavior, response format, or any other side effects. The description is consistent with the read-only annotation and adds minimal extra behavioral context, so a 3 is appropriate.

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

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

The description is a single, front-loaded sentence that defines the resource and includes the REST endpoint. Every word earns its place; there is no redundancy or unnecessary 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 list tool with two optional filters and no output schema, the description provides adequate context: it names the resource, describes what macros are, and gives the endpoint. However, it omits any mention of pagination or return format, which would be expected for a list endpoint. Given the low complexity, this 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%, with both 'access' and 'active' parameters already documented in the input schema. The description adds no additional parameter information, so it does not elevate beyond the schema baseline. A score of 3 is the baseline for high schema coverage.

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 clearly states the tool lists macros and defines them as 'reusable sets of ticket actions/replies agents apply'. This is a specific verb+resource combination that distinguishes it from sibling tools, none of which target macros.

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 by naming the resource and REST endpoint, but it does not explicitly state when to use this tool versus alternatives or provide any exclusion criteria. No alternate macro-list tool exists among siblings, so the ambiguity is low, but guidance is still implicit 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?

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds offset pagination as a behavioral trait and specifies the REST endpoint, which is useful beyond the annotation. However, it does not detail pagination edge cases, rate limits, or response structure.

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 extremely concise with two sentences, front-loading the core purpose. Every word adds value, including the pagination note and REST endpoint. No wasted text.

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

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

Given the low complexity of a paginated list operation, the description is complete enough. It covers the operation and pagination style, and the schema handles parameter details. No output schema exists, but for a standard list endpoint the agent can infer the return shape. Slightly more detail about response contents would make it perfect, but it is adequate.

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

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

Schema coverage is 100% and both parameters are fully described in the schema. The description does not add any parameter meaning beyond what the schema already provides, so 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 clearly states 'List organizations' with a specific verb+resource, and the REST endpoint further clarifies the operation. It is easily distinguished from sibling tools like zendesk_get_organization (singular) and other list 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?

The description gives no explicit guidance on when to use this tool versus alternatives. It implies use for listing organizations but does not mention when to prefer it over zendesk_get_organization or other list operations. No exclusions or alternative recommendations are provided.

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 readOnlyHint annotation already signals a safe read operation. The description adds the optional score filter and API endpoint, but these are either present in the schema or are factual details rather than behavioral traits (e.g., no pagination specifics, no response format). It does not contradict 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?

The description is a single concise sentence that front-loads the core purpose ('List customer satisfaction ratings') and mentions filtering. 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 read-only list tool with two optional parameters and complete schema descriptions, the description is adequate. It lacks explicit details about pagination behavior or return payload, but the page parameter is documented. A small gap remains regarding response structure, so 4.

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

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

Both parameters have thorough descriptions in the schema (100% coverage). The description's mention of filtering by score adds no new meaning beyond the schema's parameter description. 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 clearly states the tool lists customer satisfaction (CSAT) ratings with an optional score filter, and references the specific Zendesk REST endpoint. It is distinct from sibling tools which target tickets, users, organizations, etc.

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 for listing CSAT ratings and mentions optional filtering, but it provides no explicit guidance on when to prefer this over alternatives or any exclusions. There are no direct alternative tools for satisfaction ratings, so the context is clear but not fully 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?

The readOnlyHint annotation already covers safety, so the description adds value by disclosing that both public replies and internal notes are returned, and that the order is oldest first. It also mentions the REST endpoint, providing extra context beyond 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 sentences, with the core purpose front-loaded and the REST endpoint reference kept concise. 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 read-only list tool with full schema coverage and no output schema, the description covers the essential behavioral details: what is listed, the inclusion of internal notes, and ordering. Pagination is adequately documented in the schema, so the description is complete enough.

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 each parameter (id, page, per_page) already documented in the schema. The description does not add additional parameter semantics, so 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 clearly states the verb 'List' and the resource 'comments on a ticket', specifying they include public replies and internal notes, and orders them oldest first. This distinguishes it from siblings like zendesk_add_ticket_comment and zendesk_get_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?

The description provides clear context (lists comments on a ticket, including public and internal notes, oldest first) which implicitly tells when to use it. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to differentiate from add/update operations.

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 the read-only nature. The description adds that it covers both standard and custom fields and mentions the REST endpoint, which is useful but does not delve into response format or pagination. The added context is modest, so a 3 is appropriate.

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

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

The description is two sentences, front-loaded with the core purpose, and contains no filler. The REST endpoint reference is a useful addition without unnecessary verbosity.

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 list tool with a read-only annotation, the description is nearly complete. It gives the purpose, the scope, and the API endpoint. It does not outline response structure, but for a straightforward list operation this is not a major 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?

The input schema has zero parameters, so the baseline is 4. The description adds no parameter-specific details because there are none, but it clarifies the tool's scope (listing fields) 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?

The description clearly states the tool lists all standard and custom ticket fields, with a specific verb and resource. It distinguishes from sibling tools like list_tickets or list_groups by focusing on ticket fields.

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 provides explicit use context: it is useful for discovering field ids/values before creating or updating tickets. It does not explicitly mention alternatives, but the use case is clearly conveyed.

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 offset pagination mechanism and the REST endpoint, which is useful context, but it does not disclose other behavioral aspects such as result size limits or the absence of filtering capabilities.

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 a single sentence that front-loads the purpose, includes a technical reference, and contains no irrelevant information. Every word earns its place, exemplifying concise structure.

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

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

Given the simple nature of the tool, the schema covers parameters, and annotations cover safety, the description is minimally adequate. However, it would be more complete if it noted that this is an unfiltered list and pointed to zendesk_search for filtering, as seen in the high-caliber example.

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 each parameter fully described and enums provided. The description adds no additional parameter meaning beyond what the schema already states, 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 the specific verb 'List' with the resource 'tickets' and adds pagination details ('offset pagination') and a REST endpoint reference, making the core function clear. However, it does not explicitly distinguish itself from sibling tools like zendesk_search or zendesk_execute_view, which also return lists of tickets in different ways.

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 guidance is provided on when to use this tool versus alternatives. It does not state that this returns all tickets unfiltered or that zendesk_search should be used for filtered queries, leaving the agent to infer appropriate 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?

The annotation readOnlyHint=true already indicates a safe read operation. The description adds the REST endpoint 'GET /views.json' and the notion of 'curated ticket lists', but it does not disclose additional behavioral traits like pagination, ordering, or output format. This is 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 sentences, front-loaded with the core action, and every word earns its place. It efficiently includes the purpose, clarification, alternative tool, and REST endpoint without fluff.

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 list tool with no required parameters, no output schema, and a read-only annotation, the description fully covers what the tool does, how to run one of the views, and the underlying API call. No essential context 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%, with both parameters ('access' and 'active') having clear descriptions. The description does not add parameter details, but the schema carries the full semantic burden, so a baseline score 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 clearly states the verb 'List' and the resource 'saved ticket views', and clarifies what views are with 'curated ticket lists'. It also distinguishes from the sibling zendesk_execute_view by saying 'Use zendesk_execute_view to run one.'

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 explicitly provides an alternative: 'Use zendesk_execute_view to run one.' This tells the agent when to use this list tool versus the execution tool. No further exclusions are needed for a straightforward listing operation.

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 provide readOnlyHint=true, covering the read-only safety aspect. The description adds valuable behavioral context with query syntax examples and the REST endpoint, aiding the agent in constructing valid queries beyond what the annotation provides.

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 sentences, front-loaded with the purpose, followed by useful examples and the REST endpoint. Every sentence contributes substantive information with no filler.

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

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

The description covers the core query syntax and the unified search scope, and the 'page' parameter description addresses pagination. There's no output schema, but the return format is intuitive for a search tool; a minor gap is the lack of explicit result format details.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches the 'query' parameter by offering multiple concrete examples using Zendesk syntax across different entity types, exceeding the schema's single example and clarifying how to combine filters.

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 clearly states 'Unified search across tickets, users, organizations and groups' with a specific verb 'search' and clear resource scope. It effectively distinguishes from sibling zendesk_search_users by covering multiple entity types.

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 provides clear context for when to use the tool: for cross-entity searching, with concrete examples for tickets, users, and organizations. However, it does not explicitly mention alternatives like zendesk_search_users for user-only searches, so it lacks explicit exclusions.

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

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

Annotations declare readOnlyHint=true, and the description reinforces this with 'GET /users/search.json'. No additional behavioral context is provided (e.g., pagination behavior, result limits, or response format), but given the annotation coverage, a baseline score is appropriate.

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

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

Two sentences, no redundancy. The first sentence states the function, the second provides the REST endpoint. Every word 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 search tool with good annotations and full schema coverage, this description is largely complete. It does not mention the return format or edge cases (e.g., empty results), but the tool's low complexity and pagination parameters in the schema cover the main usage needs.

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%—each parameter (query, page, per_page) already has clear descriptions. The description's mention of 'name, email, phone' adds slight context for the query parameter but does not go beyond the schema's existing explanations. Baseline 3 is justified.

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 clearly states the tool's function: 'Find users by name, email, phone, or other attributes.' This gives a specific verb ('find') and resource ('users') plus the matching REST endpoint, distinguishing it from siblings like zendesk_get_user (by ID) and zendesk_search (cross-resource).

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 context: use when searching for users by attributes rather than by known ID. However, it does not explicitly name alternatives or exclusion criteria (e.g., 'use zendesk_search for searching all resource types'). The purpose is clear enough to guide basic selection.

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 description labels the operation as 'MUTATING', which aligns with the destructiveHint annotation but adds little beyond it. It mentions the REST endpoint and the need for an id, but does not disclose broader behavioral traits like whether updates are reversible or any rate limit implications. Given the annotation already signals mutation, the description provides minimal extra context.

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 sentences, front-loaded with 'MUTATING' and the action verb. Every word contributes to understanding the tool's purpose and requirements, with 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 multi-parameter update tool with no output schema, the description covers the core requirement (id plus at least one field) and lists common fields. It does not describe the response format or error behavior, but the schema handles parameter details and the tool is relatively straightforward.

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 fully documents all parameters. The description reiterates some field names and mentions 'or a comment' without precisely mapping to the comment_body parameter, adding marginal value over 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?

The description clearly states the action ('update an existing ticket') and specifies the resource. It also lists the mutable fields and the required ticket id, effectively distinguishing it from siblings like create_ticket or add_ticket_comment.

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 indicates when to use the tool: to update an existing ticket with at least one field. It implies this is the right tool for modifying ticket attributes, but it does not explicitly exclude alternatives such as zendesk_add_ticket_comment for adding comments. The context is sufficient but not exhaustive.

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