Zammad MCP by usefulapi

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

Adds real context the annotations do not carry: the agent-token requirement (customer tokens are refused and why), the fact that the ticket's other data is untouched, and the exact endpoint/payload shape. One tension: annotations declare destructiveHint=true while the text says existing ticket data is unchanged — a mild mismatch about destructiveness, though both agree this is a write.

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

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

Front-loads 'WRITE' and 'INTERNAL', then auth precondition, then side-effect, then endpoint. Every clause carries information; nothing is 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 3-parameter write with no output schema and full annotation coverage, the description supplies the auth precondition, the visibility semantics, the non-mutation guarantee and the wire format. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so ticket_id, body and subject are already documented with types and length bounds. The description only adds the 'ONE ticket' cardinality constraint and the note/public distinction, 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?

States a specific verb and resource ('add an INTERNAL note ... to ONE ticket') with the key qualifier that distinguishes it from a customer reply. An agent can immediately tell this apart from zammad_reply_to_ticket 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?

The description makes the use case unambiguous: visible to agents only, never e-mailed to the customer, which implicitly routes customer-facing messages to reply_to_ticket. It stops short of naming that sibling explicitly, so the exclusion is inferable rather than spelled out.

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

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

Goes well beyond the annotations: it discloses that no e-mail is sent by the call itself but instance triggers may send one, that new users are never created, and that the article is recorded as customer-authored. These side-effect details are exactly what annotations (destructiveHint=true, openWorldHint=true) cannot convey and are critical for a 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?

Three sentences, front-loaded with the operation class ('WRITE') and the core action, then the side-effect caveat, then the negative constraint. Capitalized emphasis on ONE/EXISTING aids scanning without padding; no sentence is redundant.

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

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

For a 10-parameter, non-idempotent write tool with no output schema, the description covers prerequisites, trigger behavior, and the endpoint. It omits any mention of what is returned (e.g. the created ticket id), which an agent may need to chain a follow-up call, but that is a minor gap given the otherwise thorough disclosure.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot: the customer field must reference an existing user and the choice between customer (e-mail) and customer_id (id) is a mutually exclusive input, plus the note/phone article semantics. It does not explain defaults for state, priority, or owner, which the schema handles.

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 ONE new ticket') plus scope qualifiers: for an EXISTING customer, in a group, with a first article attributed to the customer. The 'WRITE:' prefix and 'ONE' immediately separate it from sibling read tools (zammad_get_ticket, zammad_list_tickets) and from update/reply 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?

Gives explicit prerequisites and constraints: the customer must already exist ('It never creates new users'), provide either an e-mail or a user id, and the article type is note or phone. It does not explicitly name the alternatives (zammad_reply_to_ticket, zammad_add_internal_note) for adding messages to an existing ticket, so routing guidance 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, openWorldHint, and destructiveHint=false. The description adds value by listing the returned fields (id, name, e-mail, roles, groups) and framing the call as a token-permission check, though it does not cover rate limits or auth-edge cases.

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

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

Two tight sentences plus the raw endpoint. The returned data is front-loaded, followed by the practical use, and the API path is a useful append. 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 no-parameter GET with annotations covering safety and no output schema, the description supplies the resource identity, return fields, and a concrete use case. Nothing essential is missing.

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

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

The tool takes zero parameters, so per the rules the baseline is 4. There are no parameters for the description to clarify further.

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 precisely identifies the resource as the user tied to the current access token, listing the returned fields. This inherently distinguishes it from the sibling `zammad_get_user`, which retrieves an arbitrary user by identifier.

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 states when to use it: 'Use it to confirm the connection and the token's permissions.' However, it does not name alternatives or exclusions, so it falls short of a full 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context by listing the returned fields and the underlying endpoint, but says nothing about auth requirements or behavior when the id does not exist.

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

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

Two compact fragments with zero filler; the resource identity and return shape are front-loaded before the endpoint detail. Nothing can be cut without losing information.

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

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

For a single-entity read with annotations covering safety and no output schema, the field enumeration gives the agent enough to know what comes back. Only the error/not-found path is unaddressed, a minor gap.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'Zammad organization id.' The description reinforces this with 'by id' but adds no format or constraint detail beyond the schema's integer/minimum bounds. 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 ('One organization by id') and enumerates the returned fields, so the agent knows exactly what it retrieves. It distinguishes itself from the list/search siblings only implicitly via 'by id' rather than naming them, which keeps it 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 implied: fetch a single organization when you already have its id, as opposed to zammad_list_organizations or zammad_search_organizations. There is no explicit when-to-use or when-not-to-use guidance, and the alternatives are never named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the expand=true behavior and the concrete field set returned (escalation, article count, organization), which an agent cannot infer from the annotations.

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

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

A single sentence plus the underlying endpoint, with the identifying constraint front-loaded and zero filler. Every clause earns its place by either disambiguating the id or describing the payload.

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

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

With no output schema, the description compensates by enumerating the returned fields, and the single required parameter is fully documented in the schema. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the schema description already explains that ticket_id is the URL number, not the ticket number. The description restates the same distinction, so it adds reinforcement but no new syntactic or semantic 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 retrieval ('One ticket') scoped by a specific identifier, and enumerates the returned fields. The 'by its numeric id (not the ticket number)' clause distinguishes it from the list/search siblings that operate on queries or numbers.

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?

Clearly frames the retrieval context (single ticket, numeric id, expanded payload) and preempts the common mistake of passing the 5-digit ticket number. It does not explicitly name an alternative like zammad_search_tickets or zammad_list_tickets for when the id is unknown, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false. The description adds valuable return-shape context by specifying that the result includes the full body, headers, and attachment names, which matters because no output schema exists. It does not cover error handling or rate limits, but those are less critical here.

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

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

Two tightly written sentences: the first states the return content, the second gives the endpoint. No filler or redundancy; front-loaded with the core purpose.

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

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

With no output schema, the description compensates by detailing the return fields (full body, headers, attachment names). Combined with annotations covering safety and a fully documented single parameter, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% for the single article_id parameter, including its origin from zammad_list_ticket_articles. The description adds no further parameter syntax or constraints beyond what the schema provides. 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?

Specifies a concrete verb (GET), a single resource (ticket article), and the scope (one article by id, with full body/headers/attachments). This naturally distinguishes it from the sibling list 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?

The description states what the tool returns but offers no guidance on when to choose it over alternatives like zammad_list_ticket_articles or zammad_get_ticket. It implies retrieval by id but provides no explicit conditions, exclusions, or workflow context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description still adds real context beyond that: it tells the agent no credentials are returned (useful for deciding whether the response is safe to surface) and documents the underlying call with expand=true, implying an expanded field set. It does not cover failure behavior such as a missing id.

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

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

Front-loaded and efficient: the resource and returned fields come first, then the credentials caveat, then the endpoint. The trailing raw endpoint string (GET /api/v1/users/{id}?expand=true) is mild redundancy that an agent rarely needs, but nothing else is wasted.

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

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

For a simple single-parameter read tool with no output schema, the description is nearly sufficient: it names the fields returned, the subject types, and a security-relevant exclusion. It is slightly incomplete on error cases (unknown/invalid id) and on whether the id space is shared across customers and agents.

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

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

With a single parameter at 100% schema description coverage, the schema already defines user_id as 'Zammad user id.' with positivity bounds. The description only restates that retrieval is 'by id' and adds no format, range, or source hints for obtaining the id, 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 ('One user ... by id') and enumerates the returned fields (name, e-mail, phone, organization, roles, VIP flag, notes), so an agent knows exactly what this retrieves. The 'by id' scope implicitly separates it from zammad_search_users, which handles filtered lookup, and it clarifies that both customers and agents are covered.

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

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

Usage is only implied: 'by id' signals this is the lookup to use when the numeric id is already known, in contrast to search_users. There is no explicit when-to-use/when-not statement, no prerequisite (e.g., permissions to read arbitrary users), and no named 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 already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value beyond them by disclosing the required admin.group permission and the concrete failure mode with an agent-only token, which the annotations do not 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 dense sentences with zero waste: payload contents first, then permission prerequisite and failure mode. Front-loaded and immediately actionable.

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

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

With no output schema, the description compensates by naming the returned fields, and it discloses the auth requirement that determines whether the call succeeds. Pagination behavior is left to the schema, which covers it adequately; only the absence of any routing guidance keeps this 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 both pagination parameters are documented inline, including the 'pass the previous reply's next_page' convention. The description contributes no additional parameter meaning, 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 resource — the ticket groups (queues) of the instance — and even enumerates the returned fields (ids, names, agent ids), so an agent knows exactly what it gets. It is naturally distinct from siblings like zammad_list_organizations or zammad_list_ticket_states, though it never names an alternative to reinforce that distinction.

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

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

Usage is implied by the resource and the disclosed prerequisite (admin.group permission; agent-only tokens fail with an authorization error), which is genuinely useful pre-call guidance. However, there is no explicit when-to-use vs. alternative statement — nothing says, for example, when to reach for groups instead of states or priorities.

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 readOnly/openWorld/non-destructive, so the safety profile is covered; the description adds genuinely useful context the annotations lack, namely the required agent token and the fields returned. It does not describe rate limits or full return shape, but it adds real value beyond structured data.

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

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

Three short, front-loaded sentences with essentially no waste. The trailing 'GET /api/v1/organizations' endpoint line is mildly redundant but still useful for context.

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

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

No output schema exists, so the description appropriately names the returned fields, and it adds the auth requirement while the schema handles pagination. For a simple read-only list tool this is nearly complete, missing only explicit sibling routing.

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

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

Schema description coverage is 100%, and both parameters (page, per_page) are fully documented in the schema including the next_page continuation hint. The description adds nothing about parameters, 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 customer organizations') and even names the returned fields (domain, VIP flag, member ids). It distinguishes itself naturally from the singular zammad_get_organization, but never explicitly differentiates from the sibling zammad_search_organizations, which is the closest alternative.

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

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

Usage is only implied: 'List' suggests enumerating the whole collection versus the search sibling, and 'Needs an agent token' gives an auth precondition, but there is no explicit when-to-use-this-vs-search_organizations guidance or exclusions. Adequate but with a clear gap.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, yet the description adds genuinely non-inferable behavior: articles are returned in order, attachments are named but NOT downloaded, and bodies are truncated at 6000 characters. The truncation limit is exactly the kind of trait an agent must know before trusting the output.

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

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

A single dense run-on sentence plus the raw endpoint, front-loaded with the resource and scope and immediately followed by the two caveats an agent cares about (truncation, attachment names only). 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?

No output schema exists, so the description carries the return-value burden and it does so by enumerating returned fields, ordering, and truncation. Combined with the annotations covering the safety profile, nothing needed to call it correctly is missing.

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

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

Only one required integer parameter with a 100% covered schema description ('Zammad ticket id.'). The description reinforces that the id scopes to 'one ticket' but adds no format or constraint detail beyond the schema, 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?

Specific verb+resource: lists all articles of a single ticket, and enumerates exactly which fields come back (sender, type, internal flag, from/to/cc, subject, body, attachment names). The phrase 'of one ticket' plus the explicit contrast with zammad_get_ticket_article makes it distinguishable from siblings without opening a schema.

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

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

Gives an explicit routing rule: 'Long bodies are cut at 6000 characters; use zammad_get_ticket_article for the full text.' That tells the agent when to switch tools, though it offers no guidance distinguishing this from zammad_get_ticket or zammad_list_tickets.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely new behavioral context that annotations cannot: it is an instance-wide enumeration and it returns both names and ids, which matters because there is no output schema.

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

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

Three tight clauses with no filler; the resource and payload shape come first, then the downstream usage, then the endpoint. The endpoint path is arguably redundant for an agent but is a minor addition.

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 carries the burden of describing returns, and it does so by naming the fields (names with ids) and giving examples. For a trivial zero-parameter lookup this is complete, though a line on ordering or whether defaults appear would make it fully airtight.

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, and it does not mislead about inputs.

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

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

The description states a specific resource (ticket priorities of the instance) and shows concrete example values ('1 low', '2 normal', '3 high'), so an agent knows exactly what comes back. It does not explicitly contrast itself with the closest sibling (zammad_list_ticket_states), so it falls 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?

'Use the names in zammad_update_ticket' tells the agent precisely why and when to call this tool: to resolve priority labels before mutating a ticket. There is no when-not guidance or discussion of alternatives, but the primary usage context is unambiguous.

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 destructiveHint=false, so safety is covered. The description adds non-obvious behavioral context the annotations cannot convey: results are permission-scoped (agents see only their groups' tickets, customers only their own) and it exposes the expand=true query behavior. It does not describe pagination mechanics or result shape, but the schema covers paging and this is a read-only list.

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

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

Two sentences, zero filler, with the visibility constraint front-loaded and the routing hint placed after the primary behavior. The endpoint reference is a compact extra.

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

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

For a read-only, no-output-schema list tool with fully documented inputs, the description covers purpose, scope/authorization, and the sibling alternative. Return format and pagination behavior are left implicit, which is acceptable given the schema documents next_page/per_page paging.

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 only two optional paging parameters, so the schema already carries the parameter documentation; baseline 3 applies. The description's mention of 'expand=true' adds a hint about response expansion not present in the schema, but it is not tied to a described input parameter.

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) plus resource (tickets) and immediately defines the scope: only tickets the token's user can see, with the agent/customer visibility rule spelled out. It also names the sibling zammad_search_tickets as the alternative, so the agent can distinguish the two 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 gives the when-to-use split: use this for unfiltered listing, use zammad_search_tickets 'for anything targeted.' That is a clear alternative-routing rule rather than an implied one.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds the shape of the return data (ids plus an active flag) even though no output schema exists, and cites the underlying GET endpoint; it omits pagination or ordering, which is negligible here.

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

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

Two short sentences, front-loaded with the resource, followed by the actionable usage hint and the endpoint. No repetition 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 trivial no-argument read that returns a small reference list, the description covers what is returned (ids and active flags), the example values, and how to consume the result. Nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly presents the call as requiring no input beyond the endpoint path.

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

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

States the specific resource (ticket states of the instance) and enumerates representative values (new, open, pending reminder, pending close, closed), which is far more informative than the title. It clearly separates itself from zammad_list_ticket_priorities by naming the exact resource, though it doesn't explicitly call out that distinction.

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

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

The sentence 'Use the names in zammad_update_ticket' gives explicit downstream context for why an agent would call this, routing toward the write tool. It stops short of stating when-not-to-use or naming alternative lookup tools, but for a zero-parameter enumeration tool the context is clear.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the description only needs to add context. It does so usefully by disclosing an auth requirement ('Needs an agent token') and the underlying endpoint, which is exactly the type of operational detail annotations cannot express. It stops short of describing return shape or error behavior.

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

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

Three short fragments with the resource front-loaded and no filler. The endpoint string is slightly redundant with the schema but usefully confirms the API object type (Ticket).

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-only list with no output schema, the definition covers what it fetches, against which object, and the auth prerequisite. The main omission is what the returned tags look like (e.g. an array of strings), which an agent might want to know.

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 well-documented ticket_id, so the schema does the heavy lifting. The description only echoes the parameter in the URL template ('o_id={ticket_id}') without adding format or constraint detail 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 states the resource precisely ('The tags on one ticket') and pins the exact endpoint, so an agent knows this returns a ticket's tags and not articles, priorities, or states. It lacks an explicit verb, but the noun phrase plus the sibling set makes the scope 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 condition selecting it over alternatives, and no mention of caveats such as missing tags or invalid ticket ids. The only implicit routing signal is the endpoint itself, which the agent must infer.

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 mark this destructive/openWorld/non-idempotent, but the description adds critical context beyond them: the reply e-mails a real person, cannot be recalled, goes to exactly one recipient, and forbids cc/bulk/attachments. It also discloses the auth requirement, which annotations don't cover.

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

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

Front-loaded with 'WRITE:' and the irreversibility warning, then recipient rules, auth, sibling pointer, and API shape. Every sentence carries decision-relevant 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?

For a destructive one-shot write with no output schema, the description covers the safety profile, recipient semantics, auth requirements, and alternative tool. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by clarifying that `to` may name only ONE other single address (no cc, no bulk) and that the default is the ticket's customer looked up from the ticket.

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

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

States a specific verb+resource with explicit scope: 'send a customer-visible reply on ONE ticket'. The 'WRITE' prefix and 'customer-visible' qualifier immediately distinguish it from the sibling zammad_add_internal_note.

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 agent: use this for customer-visible replies, use zammad_add_internal_note for an internal remark. Also states the token prerequisite (agent token, customer token refused). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds one genuinely useful behavioral fact the annotations do not carry — 'Needs an agent token' — but says nothing about pagination limits, result caps, or rate limiting beyond what the schema states.

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

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

Three short sentences, front-loaded with the purpose, then the auth prerequisite, then the endpoint. Nothing is padded and each clause carries distinct information.

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

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

For a read-only search with fully documented parameters, the description covers purpose, auth, and endpoint. With no output schema, it could say more about the response shape (e.g. that results are paged with a next_page token), though the page parameter's schema text partly compensates.

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 page, per_page and query are already documented (including the next_page pagination hint). The description only marginally extends this by noting domain is searchable, where the schema example mentions just an organization name. 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+resource ('Search customer organizations') plus the searchable fields (name, domain), so it is clearly distinct from get_organization or list_organizations. It stops short of naming those siblings explicitly, so the differentiation is inferred rather than stated.

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

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

The verb 'Search ... by name or domain' implies the lookup use case, and the required 'query' makes the intent reasonably obvious. However, it never says when to prefer this over zammad_list_organizations or zammad_get_organization, and gives no guidance on query construction or empty-result handling.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine value with types beyond that: the shape of the reply (ids plus names for group, state, priority, owner, customer) and the underlying expand=true endpoint, which no structured field 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?

Front-loaded with the core purpose and the query syntax, followed by reply shape, with no filler sentences. It is dense but every sentence contributes; the trailing GET endpoint is the only slightly extraneous fragment.

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

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

With no output schema, the description compensates by describing the reply contents, and it covers how to compose the query and the Elasticsearch prerequisite. Pagination is only covered by the schema's own parameter descriptions, which is acceptable given their coverage, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema's terse 'Search query.' by explaining the query language with concrete examples (state.name:open, customer.email, AND, plain-word text search). That meaningfully enriches the most important parameter; page/sort/order parameters remain schema-only.

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 (tickets) and details the query syntax the tool accepts, so the agent knows exactly what it does. It never names zammad_list_tickets as the alternative, so the distinction from the sibling list tool is left implicit rather than explicit.

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

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

It usefully notes that field-syntax queries require Elasticsearch on the instance, which is real usage guidance. However it never says when to prefer this over zammad_list_tickets or when a plain-word search is preferable, so routing between the two search/list siblings is left to inference.

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

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

Annotations already cover readOnlyHint, openWorldHint and destructiveHint, but the description adds genuinely useful behavioral context beyond them: it discloses the auth requirement ('Needs an agent token') and the return shape ('profile fields (no credentials)'), which is important for a user-listing tool. It stops short of describing rate limits 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?

Three short sentences, front-loaded with the purpose and searchable fields before auth and endpoint details. The raw endpoint string (GET /api/v1/users/search?expand=true) is marginally extraneous but still earns its place for debugging, so structure is efficient overall.

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 carries the return-value burden and does so at a high level ('profile fields (no credentials)'), plus it flags the auth requirement. Pagination is handled by the schema (next_page reference), leaving only minor gaps like result ordering or exact field list.

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

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

Schema description coverage is 100%, so all three parameters (query, page, per_page) are already documented in the schema, including pagination defaults. The description's list of searchable fields loosely echoes the query parameter but adds no syntax or format guidance beyond what the schema provides, 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 (search) and resource (users) and enumerates the searchable attributes (name, e-mail, login, phone, organization), so the agent knows exactly what this matches. The resource name distinguishes it from zammad_search_tickets and zammad_search_organizations, though the relationship to zammad_get_user (single lookup vs search) is left implicit.

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 its usage context (find customers/agents by attribute) but never states when to prefer it over zammad_get_user for a known ID or over the organization search. No exclusions or prerequisites for selection are given beyond the implicit 'search vs fetch' distinction.

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?

Goes well beyond the annotations by disclosing that instance triggers still fire and that closing/reassigning can email the customer or agent, plus that delete/remove/merge states are refused. It also clarifies the destructiveHint rather than contradicting it: the only destructive side effects are notification-inducing state changes, not data loss.

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

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

Five tight sentences: the WRITE prefix and field list are front-loaded, followed by value sources, the conditional requirement, the safety boundary, the side-effect warning, and the endpoint. 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?

For a 7-param mutation with no output schema, it supplies the mutation boundary, side effects, and value sourcing needed to call it correctly. The remaining gap is operational context such as required permissions/roles and what happens to fields omitted from the call.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds genuine cross-parameter meaning the schema cannot, namely that pending_time is conditionally required when state is a pending state, and that owner must be an agent id. Field-level examples (Sales::Europe, 'no owner' id 1) duplicate schema descriptions.

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

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

Names the verb (change fields), the exact resource (ONE ticket), and enumerates the mutable fields (state, priority, owner, group, title). The 'ONE ticket' scope plus 'Never deletes, removes or merges' cleanly separates it from zammad_create_ticket and zammad_reply_to_ticket without opening the schema.

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

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

Explicitly routes the agent to zammad_list_ticket_states / zammad_list_ticket_priorities / zammad_list_groups to obtain valid names, and states the pending_time prerequisite for pending states. It stops short of naming a sibling to use instead (e.g. for bulk changes or article replies), so it is strong context without explicit exclusions.

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