Kayako MCP by usefulapi

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

Annotations supply destructiveHint=true and the title, and the description adds genuinely useful behavioral context beyond that: the operation is additive ('keeping its existing tags') so the agent knows it does not clobber existing tags, plus the concrete HTTP method and endpoint. It does not cover auth requirements, rate limits, or failure behavior, so it is not exhaustive.

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 clauses with zero filler, and the mutation nature is front-loaded with 'WRITE:'. The trailing endpoint string is mildly redundant but useful for traceability.

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

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

For a simple two-parameter mutation with full schema coverage, no output schema, and annotations covering the destructive flag, the description supplies endpoint, method, and additive semantics. Little an agent needs to call it correctly is missing, though permission/auth context is absent.

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

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

Schema description coverage is 100% (both case_id and tags are documented, including 'Comma-separated tags to add'), so the schema carries the parameter semantics. The description adds nothing about parameter format or constraints, making 3 the correct baseline.

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

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

States a specific verb and resource ('add tags to a case') and adds a scope qualifier ('keeping its existing tags') that distinguishes it from a hypothetical replace/set-tags operation. It does not explicitly name the closest sibling (kayako_update_case), which may also touch tags, so it falls just short of full sibling differentiation.

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

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

The 'WRITE:' prefix and the additive phrasing imply when the tool applies (mutating tag state on an existing case), but there is no explicit when-to-use vs. alternative guidance or mention of prerequisites. Usage is inferable rather than stated.

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

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

Annotations only supply destructiveHint=true, so the description carries most of the burden and does well: it flags this as a WRITE, explains that channel MAIL actually sends the first message to the customer from the mailbox in channel_id, and that NOTE emails nobody — the key irreversible side effect. It doesn't mention auth/permission requirements, but the consequential behavior is disclosed.

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

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

Three tight sentences, front-loaded with the WRITE warning, then the channel branching, then the id-lookup pointers, then the raw endpoint. Nothing is padding and the most decision-relevant content comes first.

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 15-parameter mutation with a nested field_values object and no output schema, the description covers the critical required-parameter workflow and where to source foreign ids. A few optional fields (form_id, assignment ids) are left undocumented, but nothing an agent must know 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 60%, so the description needs to compensate for the undocumented params and partially does: it explains channel/channel_id semantics and points to kayako_list_case_options for status_id, priority_id and type_id. However form_id, assigned_team_id and assigned_agent_id remain unexplained in both places, so coverage is incomplete.

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

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

Opens with a specific verb and resource — 'WRITE: open a new case (conversation) for a requester' — and clarifies the create-vs-reply-vs-update distinction implicitly through 'new case' and the channel semantics. An agent can tell this apart from kayako_reply_to_case and kayako_update_case 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 clear operational context: which channel to pick (MAIL emails the customer, NOTE is internal and sends nothing) and routes the agent to kayako_list_channels for channel ids and kayako_list_case_options for status/priority/type ids. It lacks an explicit when-not rule (e.g. use reply_to_case for follow-ups), but the create condition 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 only supply destructiveHint=true, so the description carries most of the burden and delivers real context: this is a WRITE, no password is set, and required fields vary by role. It does not disclose permission/auth requirements, duplicate-handling behavior, or what the response contains, which are meaningful gaps for a mutation.

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

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

Front-loaded with 'WRITE: create a user' and packed into roughly two sentences with no filler; the role-conditional clause and the 'no password' caveat both earn their place. The trailing 'Kayako: POST /api/v1/users.json' is mildly redundant but useful for agents that reason about endpoints.

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 an 8-parameter mutation with nested objects (field_values) and no output schema, the description covers required-field conditionals well but omits what the call returns — notably the new user's id, which the stated use case (requester_id on a new case) directly depends on. That missing return-value guidance leaves a real hole given no output schema exists.

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

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

Schema coverage is already 75%, so the baseline is 3, but the description adds cross-field conditional logic (email/team_ids required for collaborator/agent/admin) and the provenance of role_id via kayako_list_roles. The role-conditional requirement partially duplicates the schema text, keeping it just below a 5.

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

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

States a specific verb+resource ('create a user') and immediately scopes the typical case ('typically a CUSTOMER to use as requester_id on a new case'), which distinguishes it from kayako_get_user, kayako_list_users, and kayako_create_case. An agent can select this tool without opening any schema.

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

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

Explicitly routes the agent to kayako_list_roles for role_id and states the conditional requirement (collaborator/agent/admin roles require email and team_ids). It lacks a 'when not to use' clause — e.g. checking for an existing user first to avoid duplicates — so it gives clear context but no 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 only supply readOnlyHint=true, so the description usefully adds behavior: the localized title/content expansion, the include default of 'locale_field' and its readability effect, and the exact API call. It omits auth/permission requirements, but for a read-only GET that gap is minor.

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

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

The scope and return contents are front-loaded in a single sentence, with the endpoint appended as a compact reference. Nothing feels padded, though the endpoint suffix is only marginally useful.

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 (titles, contents, status, section, tags, votes, URL) and explaining the expansion default. For a simple two-param read tool, an agent has what it needs to call 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%, so both parameters (article_id and include) are already documented, including the 'locale_field' default note. The description's mention of the include default largely restates the schema, so baseline 3 applies.

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

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

States a specific verb ('Fetch') and resource ('one knowledge-base article'), and the singular scope distinguishes it from the sibling list tool kayako_list_articles. It does not name that sibling, so it falls short of the 5-level sibling differentiation.

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

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

There is no explicit when-to-use or when-not-to-use statement, and no routing to alternatives like kayako_list_articles or kayako_search_help_center. The 'fetch one article by id' framing implies the usage context, which lands at the implied-usage level.

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

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

annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds useful context by listing the field groups the response contains and disclosing the underlying endpoint (GET /api/v1/cases/{id}.json), but says nothing about not-found behavior, permissions, or pagination.

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

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

Two sentences, front-loaded with the core purpose and retrieval-by-id, followed by parameter hints and the endpoint. The middle field enumeration is dense but earns its place by previewing the return shape in the absence of an output schema.

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

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

For a simple read tool with no output schema, the description compensates by previewing returned fields and the underlying endpoint, and it covers both optional parameters. Only edge-case behavior (invalid id, access denied) is unaddressed.

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 restates the include examples and the fields='+tags' syntax already documented in the schema, adding no new meaning such as valid resource-type values or the '*' expansion behavior.

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

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

States a specific verb and resource ("Fetch one case (conversation) by id") and enumerates the returned content (subject, requester, status, SLA metrics, etc.). The phrase "one case by id" cleanly separates it from kayako_list_cases and kayako_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 "by id" framing implies the tool is for single-case retrieval rather than listing, but no sibling (kayako_list_cases, kayako_search) is named and there is no when-not guidance. The only directive sentences concern parameters (include, fields), not tool 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 readOnlyHint annotation already marks this as a safe read, so the bar is lower. The description still adds value by naming the returned fields (name, role, teams, locale) and framing it as a credential/subdomain validation call, though it says nothing about auth failure behavior or errors.

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 core purpose before the practical use case and the raw endpoint. Every sentence carries distinct 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 zero-parameter read tool with no output schema, the description supplies both what comes back (name, role, teams, locale) and why you would call it. Nothing an agent needs to invoke 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 parameter semantics default to the baseline of 4. The description correctly does not invent or discuss inputs, and nothing is left ambiguous on the calling side.

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 (Fetch) and resource (the Kayako user these credentials belong to), and the phrase 'these credentials belong to' cleanly separates it from kayako_get_user, which targets an arbitrary user. An agent can distinguish the two siblings 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?

Gives a concrete use case — 'a cheap way to confirm the subdomain and credentials work' — which tells the agent when this tool is the right call. It implies the alternative (get_user for other users) but never states an explicit when-not or exclusion.

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

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

readOnlyHint=true already establishes this as a safe read, so the bar is lower. The description adds useful content about what the record contains and how include expands references, but says nothing about error/not-found behavior or the shape of the returned payload.

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

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

Two tight sentences with the core purpose front-loaded and the return-field inventory following. The trailing 'Kayako: GET /api/v1/users/{id}.json' endpoint note adds little for an agent and is the only near-wasteful element.

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-by-id tool with readOnlyHint, a fully documented two-parameter schema, and no output schema, the description does well by enumerating the fields an agent receives and explaining include expansion. Only error/not-found handling is unaddressed.

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 both user_id and include are already documented with their own examples. The description's include='identity_email,organization' example is mildly useful but largely overlaps the schema, so this is a baseline 3.

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

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

States a specific verb and resource ('Fetch one user by id') and even enumerates the fields returned, which clearly separates it from kayako_list_users and kayako_get_me in spirit. 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 'fetch one user by id' framing implies this is the single-record retrieval path, but the description never says when to prefer it over kayako_list_users (bulk) or kayako_get_me (self). No prerequisites or when-not conditions are given.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds real context beyond that: titles and contents come back as locale references unless include='locale_field', which affects how results must be interpreted, plus the underlying endpoint. It still says nothing about pagination or result volume, so not a 5.

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

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

Two sentences with the primary purpose front-loaded and no filler; the endpoint reference is arguably redundant but compact. Efficient and readable without 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?

With annotations covering the safety profile, full schema coverage, and no output schema to explain, the description supplies the one non-obvious behavior (locale-reference returns). The only gap is pagination/return-volume guidance, which is minor 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?

Schema coverage is 100%, so the baseline is 3, but the description earns extra credit by clarifying the semantics of include (locale reference expansion) and filter (PUBLISHED/PINNED), which the schema documents only tersely. The section/tags/limit parameters are left entirely to 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 opens with a specific verb+resource ('List knowledge-base articles') and enumerates the optional scoping facets, distinguishing it from the singular kayako_get_article and from search tools. It stops short of explicitly naming a sibling it should be preferred over, so it lands at a clear-but-undifferentiated 4.

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 sketches usage ('optionally by section, tags, or PUBLISHED / PINNED'), which implies when the filter facets apply, but it never states when to reach for this list versus kayako_search_help_center or kayako_get_article, and gives no exclusions or prerequisites. Implied usage only.

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

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

readOnlyHint=true already declares the safe-read profile, so the description only needs to add context beyond that. It does: it gives the underlying endpoint (GET /api/v1/cases/{statuses|priorities|types}.json) and the shape of returned records (id, label, type/level). It omits auth requirements, rate limits, and pagination, which keeps it short of a 5.

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

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

A single dense sentence front-loads the verb and resource, with the endpoint appended for reference. The parenthetical field lists are information-dense but each earns its place; the sentence is slightly packed but not padded.

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

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

With no output schema, the description usefully compensates by naming the returned fields per option kind, so an agent knows what it will get back. Missing only ancillary details such as auth or ordering, which is a minor gap for a simple read tool.

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

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

Schema coverage is 100% and the single 'kind' enum is already self-documenting, so the baseline is 3. The description adds genuine meaning by mapping each kind to its downstream referencing parameter (status_id/priority_id/type_id) and to the returned field set, which the schema does not convey.

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

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

States a specific verb (list) and the exact resources (case statuses, priorities, types), and even enumerates the returned field shapes for each. It is clearly distinguishable from siblings like kayako_list_cases, which list cases rather than the option dictionaries used to populate case 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?

Explicitly states the purpose context: these are 'the ids needed for status_id / priority_id / type_id when creating, updating or replying to a case', which routes the agent to the sibling tools that consume them. However, it offers no when-not-to-use condition or explicit comparison against an 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 only declare readOnlyHint=true; the description adds non-obvious behavior: newest-first ordering, the default exclusion of activities, and the constraint that before_id/after_id can be used only one at a time. It also names the underlying endpoint.

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 resource and return contents, then filters and pagination, ending with the endpoint. Dense and efficient, with almost 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 read-only list tool with no output schema, it covers ordering, filtering behavior, and pagination semantics. The include expansion parameter is left to the schema, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains what the key filters enum values (NOTES, MESSAGES, ALL) actually return and clarifies the mutual-exclusion rule for the pagination cursors that the schema does not state.

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 clear verb (read/list) and resource (a case's posts/timeline) and enumerates what it returns: customer messages, agent replies, internal notes. It is distinguishable from get_case and reply_to_case, though it never names a sibling explicitly.

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

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

Provides useful in-tool routing via the default exclusion of activities and the filters='NOTES'/'MESSAGES'/'ALL' guidance, but gives no explicit when-to-use-this-vs-alternatives direction relative to sibling list/get/search 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?

The readOnlyHint annotation already establishes safety, so credit goes to the added context: default ordering is newest-updated first, and nested resources come back as {id, resource_type} references unless expanded via include. It also cites the underlying endpoint, giving the agent a mental model of the call, though it says nothing about pagination limits or result size.

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: the resource and sort order come first, the filter modes follow, and the include/reference caveat plus endpoint close it out. Every clause carries information an agent would otherwise have to infer.

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 10 optional parameters but no output schema, the description covers the filtering surface, the id-fetch path, and how nested resources are returned, which is enough to call it correctly. It omits pagination behavior and any hint at the shape of a case object, which would have helped without an output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above it by clarifying the priority filter direction ('max priority level'), grouping the identity pair as one logical filter, and explaining the reference-versus-expansion behavior of include beyond the parameter's own wording.

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 with synonyms for disambiguation ('cases (conversations / tickets)') and adds the default sort order ('newest-updated first'). It does not distinguish itself from the closest sibling, kayako_list_organization_cases, nor from kayako_search, so an agent must infer which list tool applies.

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

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

It enumerates the filtering modes (status, tags, priority, requester identity, or explicit ids), which implies usage, but never states when this tool is preferable to kayako_search or kayako_list_organization_cases, nor any exclusions. Usage is inferable rather than guided.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds that the output is an enumeration of channel objects whose account.id is the value to pass downstream, plus the underlying API paths. It does not discuss pagination or result limits, which is a minor gap for a list endpoint.

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 plus endpoint paths; the workflow-critical guidance (case_id vs. omit, and where channel_id goes) is front-loaded before the REST detail. The trailing URL paths are the least essential part but are skimmable and genuinely useful for a client-side caller.

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

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

There is no output schema, so the description carries the burden of describing the return shape, and it does: an enumerated list of channel types whose account.id is the value to reuse. Combined with the two-mode invocation rules, an agent has everything needed to call this correctly and consume the result.

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 self-documenting, so baseline 3 would apply; however the description adds a cross-parameter rule not expressible in the schema ('ignored with case_id') and ties case_id/user_id to two distinct workflows. The account.id -> channel_id mapping further explains how the result feeds other tools.

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 the channels usable for a reply') and enumerates the concrete channel types (MAIL mailbox, TWITTER, FACEBOOK, NOTE), which no sibling tool covers. The two modes (existing case vs. new case) are named up front, so an agent can immediately tell this apart from kayako_reply_to_case or kayako_create_case.

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 conditional guidance: pass case_id for an existing case, omit case_id (optionally with user_id) for a new case, and notes user_id is ignored when case_id is present. It also names the downstream consumers (kayako_reply_to_case / kayako_create_case) and the exact value they expect, turning this into a routing instruction rather than a bare description.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the sort order ('newest-updated first') and the underlying GET endpoint, which is genuinely useful context, but says nothing about result counts or expansion behavior beyond what the schema's include parameter already covers.

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 filler, with the resource and scope front-loaded before the endpoint reference. Every clause earns its place.

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

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

For a simple read-only list tool with full schema coverage and an annotation declaring read safety, the description supplies scope, ordering, and endpoint. Only minor gaps remain (return envelope/pagination shape), and with no output schema that is a small omission.

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%: limit, offset, include, and organization_id are all documented in the schema, including defaults and the '*' expansion option. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('cases (conversations)') with an explicit scope: 'raised by members of one organization'. The scope does distinguish it in practice from kayako_list_cases, but the sibling is never named, so the separation 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 organizational scoping implies when this tool is appropriate (you know the org id and want its cases), but there is no explicit when-to-use, when-not-to-use, or pointer to kayako_list_cases / kayako_search for cross-org or filtered queries. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true so the safety profile is covered; the description adds real value beyond that by disclosing result ordering ('oldest first'), the shape of returned records, and the underlying endpoint. It stops short of describing pagination defaults or how 'include' affects response size, which would have pushed it higher.

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

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

Three tight sentences with the core purpose front-loaded and no filler; the endpoint reference is compact rather than verbose. This is cleanly written with nothing that feels wasted, though it is a fairly minimal statement 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 compensates by naming returned fields and ordering, and it closes the sibling-routing gap via kayako_search. Minor gaps remain around pagination behavior and how include changes the payload, but nothing essential to invoking the tool correctly is missing.

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

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

Schema description coverage is 100%, so limit, offset, and include are already documented with ranges and the expansion semantics of include. The description adds no parameter-level detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('List customer organizations') and enumerates the returned fields (name, domains, phone, custom fields) plus ordering ('oldest first'). It also distinguishes itself from kayako_search for lookup-by-name, so an agent can route 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 names the alternative tool and the exact invocation needed to select it: kayako_search with resources=['ORGANIZATIONS'] for single-organization lookup. Combined with the bulk-list framing and ordering note, the when-to-use routing 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, so the safety profile is covered. The description adds value beyond that by disclosing the underlying endpoint (GET /api/v1/roles.json) and, importantly, the shape of what comes back (id, title, type with its enum values) — useful since there is no output schema. Pagination/collection-size behavior is left to the schema.

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

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

A single dense sentence plus the endpoint reference. The purpose and the return-field enumeration come first, and there is no filler or restated boilerplate.

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

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

For a read-only list tool with no output schema, the description compensates by disclosing the returned fields and the role-type enum, and routing the agent to the dependent create tool. The only remaining gap is pagination/ordering behavior, which the schema already documents for limit/offset.

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

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

Schema description coverage is 100%: both `limit` (1-100, default 10) and `offset` already carry their own documented semantics and bounds. The description adds nothing about them, which is acceptable here, so the baseline 3 applies.

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

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

States a specific verb+resource ("List user roles"), enumerates the returned fields (id, title, type) and the full value domain of `type` (OWNER/ADMIN/AGENT/COLLABORATOR/CUSTOMER). It also names the consuming sibling (kayako_create_user), so an agent distinguishes it from kayako_list_users, kayako_list_teams and the other list 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?

Explicitly frames the tool's purpose in a workflow: this is where you get the role_id that kayako_create_user requires. That is actionable when-to-use context. It stops short of naming alternatives or exclusions, but for a supplementary lookup endpoint the routing signal 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=true), and there is no output schema, so the description's enumeration of returned fields (id, title, member count) plus the underlying endpoint (GET /api/v1/teams.json) adds genuinely non-redundant context. It says nothing about pagination behavior or ordering, which keeps it from a 5.

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

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

One front-loaded sentence plus an endpoint pointer; every clause earns its place with no filler or repetition of the title.

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

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

For a simple paginated read with a 100%-documented schema and readOnly annotation, the description supplies the missing return-shape information and the intended use case. Only the pagination/ordering behavior and the default page size are left 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% — limit and offset each have min/max, defaults, and semantics documented in the schema — so the description is not required to carry parameter meaning. It adds nothing beyond the schema, which is the correct baseline of 3 for a fully documented two-parameter tool.

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

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

States a specific verb and resource ('List agent teams'), enumerates the returned fields (id, title, member count), and — critically — explains the payoff: these are 'the ids for assigned_team_id'. That distinguishes it from credential/case/user listing 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?

The 'ids for assigned_team_id' note tells the agent exactly when this tool is the right one (resolving a team id for assignment). No explicit exclusions or named alternatives are offered, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, carrying the safety profile, so the bar is lower. The description adds two real behavioral facts not in structured data: results are ordered newest-first and the upstream endpoint is GET /api/v1/users.json. It says nothing about pagination behavior, though the schema covers limit/offset.

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

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

A single front-loaded sentence followed by a short routing clause and the endpoint. There is no filler; the scope and ordering come before the alternative-tool pointer.

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, but the list semantics, ordering, filters, and routing to kayako_search cover what an agent needs to call it correctly, and pagination/expansion details live in the schema. The one gap is that return shape for a list response is not hinted at.

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

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

Schema description coverage is 100%, so every parameter (ids, role, limit, offset, include) is already documented in the schema with enums and defaults. The description only restates the role-type and ids filters, adding no syntax or format detail beyond what the schema provides. Baseline 3 is correct 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?

States a specific verb and resource ('List users') plus the exact population covered (customers, collaborators, agents, admins) and the default ordering ('newest first'). It also names the sibling it is not (kayako_search), so an agent can distinguish it without opening either schema.

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

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

Explicitly routes lookup-by-email-or-name to kayako_search, which is a concrete when-not rule. However it does not clarify when to use this list tool versus the single-record kayako_get_user sibling, so one obvious boundary is left 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?

Annotations only provide destructiveHint, so the description carries most of the burden and does well: it discloses the crucial public-vs-internal visibility distinction ('visible only to agents' vs 'sends a PUBLIC reply to the customer') and names the underlying endpoint. It omits auth/permission requirements and 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?

Front-loaded with the WRITE marker and the highest-stakes distinction (internal vs public) first. Dense but each sentence adds real routing value; the trailing raw endpoint is mildly redundant but aids debugging.

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 12-parameter write tool with only a destructiveHint annotation and no output schema, the description covers the essential decision points (channel choice, channel_id sourcing, co-settable fields, endpoint). Missing only success/return behavior and post-call state changes.

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 67%, and the description fills key gaps the schema leaves blank: it explains channel semantics (NOTE needs no channel_id, others do) and that status/priority/assignee (status_id, priority_id, assigned_agent_id/team_id — all undescribed in the schema) can be set via this same call.

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?

Starts with 'WRITE: add a post to a case', a specific verb+resource, then explicitly splits the two behaviors: NOTE (internal) vs MAIL/TWITTER/FACEBOOK (public customer reply). This clearly separates it from siblings like kayako_create_case and kayako_update_case.

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?

Tells the agent exactly which channel value selects internal vs public behavior and where to obtain channel_id ('from kayako_list_channels with case_id'). It notes the overlap with update (status/priority/assignee can be set here) but never states when to prefer kayako_update_case instead.

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, so the safety profile is covered. The description adds real behavioral context beyond that: result shape (id, title, snippet, relevance, resource type), the 30-result cap, and the fields='*' inline-expansion behavior. It omits pagination behavior, which is minor given the hard cap.

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

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

Three tight sentences with the purpose front-loaded and no filler. The trailing 'Kayako: GET /api/v1/search.json' mapping is useful for endpoint-aware agents but is the least essential element.

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

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

With no output schema, the description usefully names the returned fields and the fields='*' expansion, and shares the result cap. Combined with a fully documented schema and a read-only annotation, an agent has enough to call this correctly; only pagination and query-language specifics remain unstated.

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 four parameters are already documented in the schema, including the fields='*' example and the 1-30 limit range. The description largely restates those facts (max 30 results, fields='*' inline), adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource set: unified search across conversations (cases), users and organizations. Scoping to those three resource kinds implicitly separates it from kayako_search_help_center and the various list_* tools, though no sibling is named explicitly.

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

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

Usage is only implied — an agent can infer this is the entry point when it lacks an id and needs to locate cases/users/orgs before calling kayako_get_case or kayako_get_user. There is no explicit when-to-use statement and no guidance on when to prefer kayako_list_cases or kayako_search_help_center instead.

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

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

Annotations only declare readOnlyHint=true. The description adds valuable contextual information beyond that: it specifies the return shape ('references, e.g. {id, resource_type: 'article'}'), names the follow-up tool, and gives the underlying HTTP endpoint. It does not mention pagination or auth requirements, but the read-only safety profile is already covered.

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 with zero waste. The core purpose and output are front-loaded, and the follow-up tool pointer is 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?

No output schema exists, so the description correctly fills that gap by describing the return format. It also directs the agent to kayako_get_article for full content. For a read-only search tool with a fully documented input schema, nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description does not add syntax, defaults, or format details for limit, offset, locale, or query constraints. The phrase 'articles and/or public conversations' loosely maps to the 'in' enum, but this is marginal 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?

States a specific verb ('Search') and resource ('the help center's articles and/or public conversations'), and explicitly routes to kayako_get_article for reading results. The scope is clear enough to distinguish it from general search or listing siblings even without naming them.

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 a clear usage pattern: use this to find references, then use kayako_get_article to read a full article. It does not state when to prefer it over kayako_search or kayako_list_articles, so no explicit alternatives or exclusions are given.

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

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

Annotations only provide destructiveHint=true, so the description carries most of the burden and does well: 'Sends nothing to the customer' is a real behavioral disclosure an agent cannot infer, and the explicit exclusion of trashing clarifies blast radius. It also pins the underlying call (PUT /api/v1/cases/{id}.json). It does not say whether omitted fields are preserved or what happens on failure.

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

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

One tight, front-loaded paragraph with the 'WRITE:' prefix leading immediately into the effect. Nearly every clause earns its place (field list, tag routing, trashing exclusion, endpoint). The endpoint string is the one mildly expendable element.

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 12-parameter mutation tool with no output schema and minimal annotation coverage, the description covers the mutable surface, the tag semantics, and the deliberately excluded destructive operation. Missing only edge behavior: partial-update semantics for omitted fields and auth/permission expectations.

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 only 25% schema description coverage across 12 parameters, the description is the primary documentation and it names nearly every updatable field, including the assignee split (team/agent) and custom fields. It adds the crucial set-vs-append semantics for tags that the schema only partially conveys. It could still clarify how custom-field multi-select CSV behavior maps to the operation.

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

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

Opens with an explicit verb+resource ('WRITE: change a case's...') and enumerates exactly which attributes are mutable (subject, requester, assignee, status, priority, type, brand, form, tags, custom fields). It also names the sibling it is not (kayako_add_case_tags) and notes that trashing is deliberately excluded, so an agent can pick it apart from the other case tools at a glance.

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

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

Gives a clear conditional: use this tool to set the tag list, use kayako_add_case_tags to append, which is exactly the distinction an agent needs. It also states a when-not (no trashing exposed). It stops short of spelling out prerequisites such as required permissions or which case states can be edited.

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