kayako

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

The description adds real behavioral content beyond the annotation: it declares the operation is additive and preserves existing tags, and pins the exact HTTP write path. This is notable because destructiveHint=true reads as conservative for what the description frames as a non-destructive append, though tagging does mutate the case resource so the annotation is defensible. It stops short of disclosing duplicate-tag behavior, error cases, or auth requirements.

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

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

Two compact clauses with the operation type front-loaded and the endpoint last; nothing is wasted. It is arguably under-specified rather than verbose, but on structure and economy it is strong.

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

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

For a two-parameter write tool with no output schema, the description covers what the tool does and its additive contract, which is the core need. It omits the response shape, duplicate-tag handling, and failure modes, leaving minor gaps an agent may need.

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

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

Schema description coverage is 100%, so both parameters are already documented (tags = 'Comma-separated tags to add.', case_id = 'The case id (integer).'). The description adds no syntax, format, or constraint information beyond the schema, 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 precise verb+resource ('add tags to a case') and immediately scopes the operation as additive ('keeping its existing tags'), which separates it from kayako_update_case. It even names the underlying write semantics (WRITE, POST endpoint) so an agent can distinguish it from the read/list siblings.

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

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

The 'WRITE' prefix and 'keeping its existing tags' imply this is the additive path rather than a tag replacement, which is implied usage guidance. However, it never explicitly says when to use this instead of kayako_update_case, nor does it state prerequisites or 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 destructiveHint=true, so the description must carry the load, and it does: it marks the call as a WRITE, discloses the real side effect (email is actually sent to the customer on MAIL, suppressed on NOTE), and names the underlying endpoint. It does not mention auth requirements or what a failed/rejected send looks like.

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 WRITE marker front-loaded and the highest-risk semantics (email vs no email) stated before the housekeeping. The trailing raw endpoint 'Kayako: POST /api/v1/cases.json' is low-value filler, but overall the text is dense and earns its length.

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-param write tool with no output schema and a nested field_values object, the description covers the creation flow, the channel fork, and prerequisite id lookups. It stops short of describing what is returned or the form_id/custom-field interaction, so an agent still has gaps.

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 60% across 15 params. The description adds genuine meaning for channel/channel_id behavior and for where status_id, priority_id and type_id values come from, but leaves form_id, field_values, assigned_agent_id/team_id, tags, cc, and html entirely to sparse schema text. Partial compensation 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?

Opens with a specific verb+resource ('WRITE: open a new case (conversation) for a requester'), defines the domain term 'case' as a conversation, and is clearly distinct from sibling kayako_reply_to_case / kayako_update_case which operate on existing cases. An agent can select it without opening the schema.

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

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

Gives concrete routing guidance: MAIL emails the customer from the channel_id mailbox, NOTE creates an internal note and emails nobody, and explicitly points to kayako_list_channels and kayako_list_case_options for id lookups. It lacks an explicit 'not for existing cases, use reply_to_case' statement, so it stops just short of full alternative coverage.

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 additional burden and delivers: it flags the WRITE operation, notes 'No password is set by this tool' (a real behavioral caveat), and explains role-dependent requirements. It adds genuine context beyond annotations, though it omits things like auth/permission scope and idempotency.

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?

Dense and front-loaded, opening with the 'WRITE:' risk marker and packing role, dependency, and password caveats into a few tight sentences with zero filler.

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

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

No output schema exists, so return values need not be described; the description covers the creation intent, role dependency, and role-conditional requirements. It leaves out permission/auth expectations for a destructive write, a minor gap for an 8-param 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?

With 75% schema coverage the baseline is 3, but the description adds cross-parameter meaning the schema lacks: role_id provenance from kayako_list_roles and the conditional requirement that email and team_ids apply to collaborator/agent/admin roles. It stops short of documenting time_zone or other params, so not 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 adds the typical intent ('a CUSTOMER to use as requester_id on a new case'), which lets an agent distinguish it from kayako_get_user, kayako_list_users, and kayako_create_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 usage context (create a customer as a requester_id) and a dependency ('role_id comes from kayako_list_roles'), plus conditional requirements for collaborator/agent/admin roles. It does not explicitly state when NOT to use it or name a direct alternative, so it falls short of a 5.

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

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

readOnlyHint=true already covers the safety profile, but the description adds real behavioral context: it discloses that 'include' defaults to 'locale_field' so titles/contents come back readable, and enumerates exactly what the payload contains. It does not mention auth requirements, but that is a minor gap given the annotation.

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

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

One front-loaded sentence that leads with the action and the returned fields; efficient overall. The trailing 'Kayako: GET /api/v1/articles/{id}.json' is mildly redundant for an agent but provides endpoint traceability without bloating the text.

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

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

With no output schema, the description carries the burden of describing the return shape and does so by enumerating the fields and the localization default. Combined with the readOnly annotation, an agent has enough to invoke it correctly, though it omits error/not-found behavior.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description's statement that include defaults to 'locale_field' duplicates the schema's own wording. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb ('Fetch') and resource ('one knowledge-base article') and enumerates the fields returned (localized titles/contents, status, section, tags, votes, URL). The singular 'one ... article' cleanly distinguishes it from the sibling kayako_list_articles without needing 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?

Usage is only implied: the single-id fetch shape makes it obvious you call this when you already have an article id, but the description never says when to use it versus kayako_list_articles or kayako_search_help_center, nor does it list any prerequisites.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context by enumerating the fields and sub-objects returned (subject, requester, assignee, status, SLA metrics, custom fields, last post preview), which is valuable given there is no output schema, though it says nothing about errors, permissions, or rate limits.

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

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

Front-loaded with the core purpose and returned fields, followed by compact parameter guidance and the underlying endpoint. Every sentence contributes, though the raw REST path is arguably extraneous for an agent that invokes a tool rather than an HTTP endpoint.

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 get-by-id tool, the description is complete: purpose, returned content, parameter usage, and safety annotation coverage are all present. Since there is no output schema, listing the key returned fields compensates adequately, and an agent has everything needed 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 the schema already documents all three parameters with examples. The description reinforces include ('expand references') and fields ('+tags' for tags) but adds little syntax or meaning beyond what the schema provides, matching the baseline for high coverage.

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

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

States a specific verb (Fetch) and resource (one case/conversation) with a clear scope constraint (by id), and enumerates the returned fields. The 'one case by id' framing distinguishes it from the sibling list/search tools such as 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?

Usage is implied: call it when you have a case id and need a single case. It describes how to use the include and fields parameters, but never states when to choose this tool over kayako_list_cases, kayako_search, or kayako_list_case_posts, nor does it mention any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful context beyond that: a latency/cost hint ('cheap'), the identity scope, and the underlying endpoint (GET /api/v1/me.json) for traceability. It does not mention auth failure behavior, which would be the natural remaining detail.

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 purpose front-loaded, the return fields parenthesized inline, and the endpoint appended as a trailing reference. No sentence is wasted and nothing is buried.

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

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

With no output schema, the description usefully compensates by naming the returned fields (name, role, teams, locale), and annotations cover the safety profile. It is nearly complete; the only slight gap is what happens on auth failure, which the 'confirm credentials work' framing hints at but does not spell out.

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

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

There are zero parameters, so per the rubric the baseline is 4. The description correctly describes a no-argument call rather than implying any input is needed.

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

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

The description states a specific verb and resource ('Fetch the Kayako user these credentials belong to') and scopes it to the authenticated identity, which cleanly separates it from the sibling kayako_get_user (an arbitrary user lookup). It also enumerates the fields returned, so an agent knows exactly what it gets.

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

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

It gives clear usage context — 'a cheap way to confirm the subdomain and credentials work' — which tells the agent when this is the right call. However, it never explicitly names an alternative (e.g. kayako_get_user) or states when not to use it, so routing between the two remains partly inferential.

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 covers the safety profile, so the description's contribution is the returned field set and the reference-expansion behavior of include. It omits auth requirements, error behavior for unknown ids, and rate limits, so it adds context but is not rich.

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

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

Two compact sentences, front-loaded with the verb and resource, then the return fields, then the include hint and endpoint. No filler and nothing buried.

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

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

With no output schema, the description usefully enumerates the returned fields and explains include's expansion role, which is what an agent needs to call it correctly. Minor gaps remain (error cases, whether include values are validated), but 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 both user_id and include are already documented with types, bounds, and examples. The description reinforces include with an example ('identity_email,organization') but adds no syntax or default beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb+resource ('Fetch one user by id') and enumerates the fields returned, which cleanly separates it from siblings like kayako_list_users, kayako_create_user, and kayako_get_me. An agent can identify the operation without opening the schema.

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

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

The 'by id' framing implies usage (single-record lookup when you already have an id), which is enough to distinguish it from list_users. However, it never explicitly says when to prefer it over kayako_get_me or kayako_search, and names no alternatives.

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 already declares this a safe read, so the bar is lower, yet the description adds a genuinely useful behavioral nuance: titles and contents come back as locale references unless include='locale_field'. That is context an agent cannot get from annotations alone, though permissions and pagination behavior remain unstated.

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 front-load the resource and filters, then add the locale caveat, with an endpoint reference tacked on. Nearly every clause earns its place; the raw HTTP path is the only mildly extraneous 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 characterizes the return values (id/reference objects, locale references unless include is set) and covers all filter dimensions. It is close to complete, missing only pagination defaults and permission notes.

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 explaining that include='locale_field' controls whether titles/contents are resolved — a semantic tie between two parameters the schema does not draw. It still leaves tags-format and limit/offset semantics 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?

States a specific verb and resource ("List knowledge-base articles") plus the available filter dimensions (section, tags, PUBLISHED/PINNED), which distinguishes it from the single-item kayako_get_article. However, it never names the closely related kayako_search_help_center, so the boundary against that sibling must be inferred.

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 phrase "optionally by section, tags, or PUBLISHED / PINNED" implies when the filters are useful, but there is no explicit when-to-use guidance and no mention of when to prefer kayako_search_help_center instead. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description notes it is an instance-scoped GET endpoint, but adds nothing on rate limits, caching, pagination, or whether the lists are user-configurable — modest value beyond 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 dense sentence that front-loads the verb and resource, with the API endpoint appended as secondary detail. Efficient with no filler, though the em-dash clause makes it slightly harder to scan than two short sentences would.

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-param, read-only lookup with no output schema, the description covers what is returned, why it matters, and the underlying endpoint. Nothing critical for correct invocation is missing; deeper response details (ordering, pagination) are the only gaps.

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 enum param is fully typed, so the baseline is 3. The description goes further by mapping each enum value to the concrete return fields (id/label/type vs id/label/level) and to the downstream id fields they feed, which meaningfully exceeds 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 (List) plus the three resources (case statuses, priorities, types) and enumerates the fields each returns. An agent can distinguish it from other list_* siblings because the resource is named precisely and the returned fields differ per kind.

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 says the ids are needed for status_id / priority_id / type_id when creating, updating or replying to a case, which gives a clear trigger for calling it. It does not name exclusions or alternative sibling tools, but the use 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 covering the safety profile, but the description adds real behavioral context: newest-first ordering, the default exclusion of activities, and the mutual-exclusivity constraint that before_id/after_id must be used one at a time.

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 what the resource is, then defaults, then filter values, then pagination, then the endpoint. Every clause earns its place with no filler.

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

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

For a read-only list tool with full schema coverage and no output schema, the description covers ordering, filtering, and pagination adequately. It does not mention the 'include' expansion parameter, but that parameter is documented in the schema, so the gap is minor.

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

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

Schema coverage is 100% so baseline is 3, but the description goes beyond the schema by mapping filter values to intent ('NOTES' for internal notes only, 'MESSAGES' for messages, 'ALL' to include activities) and clarifying the cursor pagination constraint, adding meaning the terse schema descriptions do not.

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 ('Read a case's timeline') and enumerates the post types it returns (customer messages, agent replies, internal notes), which cleanly distinguishes it from kayako_get_case (case details) and kayako_list_cases (case list).

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 explains the default behavior (activities excluded) and how filters select subsets and how to paginate, which is useful implied usage guidance. However, it never explicitly says when to choose this tool over siblings such as kayako_get_case or kayako_search, so alternatives and exclusions are 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 only declare readOnlyHint, so the description carries most of the behavioral load and does so well: it discloses result ordering (newest-updated first) and that nested resources come back as {id, resource_type} references unless `include` expands them — non-obvious semantics not derivable from the schema. It still says nothing about pagination boundaries or result-size 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?

Two dense sentences plus a one-line endpoint reference; ordering is front-loaded and every clause adds either a filter mode or a behavioral fact. 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 must cover behavior, and it covers filtering, ordering, and reference semantics adequately for a list endpoint. It omits anything about the response envelope or pagination interplay with limit/offset, which keeps it from a 5.

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, but the description adds real meaning beyond the schema: it frames `ids` as an alternative to filtering, groups the identity pair (identity_type/identity_value) as one requester lookup, and explains the reference-vs-expansion behavior of `include`.

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 scope ('cases (conversations / tickets)'), plus ordering and the two operating modes (filter vs. fetch by ids). Clear enough to distinguish from kayako_get_case and kayako_list_case_posts, though it never names a sibling to contrast against, so it falls just 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?

It enumerates the available filter dimensions (status type, tags, priority ceiling, requester identity, specific ids), which implies how to use the tool, but gives no when-to-use/when-not guidance relative to alternatives such as kayako_search or kayako_list_organization_cases.

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 covers the safety profile, so the description adds real value by disclosing that a channel's account.id is the value to forward as channel_id, and by listing the underlying REST endpoints. This return-semantics context is useful given 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?

Front-loads the purpose and channel enumeration, then the mode selection, then the output-forwarding detail, then the raw endpoint. Every sentence carries distinct, non-redundant 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 no-output-schema lookup tool, the description fully explains what is returned (channel types and the account.id to forward) and both invocation modes. Nothing an agent needs 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 coverage is 100%, so the baseline is 3, but the description adds the conditional logic the schema only hints at: case_id selects existing-case mode, and user_id applies only to the new-case mode (ignored with case_id). This clarifies the interaction between the two parameters beyond their individual 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?

States a specific verb+resource ('List the channels') and enumerates the concrete channel types (MAIL, TWITTER, FACEBOOK, NOTE). It distinguishes itself from siblings by naming the two downstream tools (kayako_reply_to_case / kayako_create_case) that consume its output.

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 two usage modes: pass case_id to list channels for replying to an existing case, or omit case_id (optionally with user_id) for a new case. It also tells the agent why it would call this tool — to obtain the channel_id needed by the reply/create tools.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context: the result ordering (newest-updated first) and the underlying API endpoint. It does not discuss pagination behavior or result shape, but for a read-only list tool that is a modest gap.

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

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

Two short sentences with the core action front-loaded; nothing is padded. The raw endpoint reference is slightly redundant for an agent but does not bloat the text.

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

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

For a read-only, 4-parameter list tool with no output schema and full schema coverage, the description covers the essentials (scope, ordering). It stops short of describing the returned case object or pagination semantics, leaving a small but real gap.

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

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

Schema description coverage is 100%, so all four parameters (limit, offset, include, organization_id) are already documented in the schema. The description adds only the notion that membership scope is implied by the org id; 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 ('List the cases (conversations) raised by members of one organization') and adds ordering semantics (newest-updated first). It implicitly distinguishes itself from kayako_list_cases by scoping to one organization, but never names that sibling explicitly.

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

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

The description implies usage (you have an organization id and want its cases) but gives no explicit when-to-use guidance, no prerequisites, and no routing to alternatives such as kayako_list_cases or kayako_search for broader queries.

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 ordering behavior ('oldest first'), the returned field set, and the underlying endpoint, which are genuinely useful beyond the annotations. It doesn't cover pagination behavior, but the schema handles 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?

Three short clauses, front-loaded with the core purpose before the alternative and the endpoint reference. No filler sentences.

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 covers scope, ordering, returned fields, and the sibling alternative, which is close to complete. It stops short of noting pagination defaults, though the schema carries those.

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 each fully documented in the schema. The description's field list refers to returned data rather than input parameters and adds 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 ('List customer organizations'), enumerates the fields returned (name, domains, phone, custom fields), and distinguishes itself from the sibling kayako_search by naming it directly.

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

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

Explicitly provides the alternative path: 'To find one by name use kayako_search with resources=["ORGANIZATIONS"]'. The agent knows when this tool is the wrong choice without opening a schema.

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

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

With readOnlyHint=true already declaring the safety profile, the description's marginal additions are the concrete enum of role types and the backing endpoint. It does not describe pagination behavior, default page size, or how many roles are typically returned, which are the traits annotations do not 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?

A single front-loaded sentence carrying purpose, return fields, downstream consumer, and endpoint. No filler; 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 annotations, the description supplies purpose, key return fields, and consumer. The only minor gap is that collection size/pagination expectations are left entirely to the schema.

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

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

Schema description coverage is 100% and both parameters (limit, offset) are fully documented in the schema with ranges and defaults. The description adds nothing about them, so baseline 3 applies.

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

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

States a specific verb+resource ("List user roles") and enumerates the meaningful fields returned, including the full enum of role types (OWNER/ADMIN/AGENT/COLLABORATOR/CUSTOMER). No sibling tool lists roles, so there is no ambiguity to resolve; the endpoint reference confirms the scope.

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

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

Explicitly gives the reason to call it: retrieving the role_id required by kayako_create_user. That is a clear usage context, but it offers no exclusion guidance or alternatives (e.g., what to do if you already know the role title) and no prerequisites.

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

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

readOnlyHint=true already establishes the safety profile, so the description only needs to add context. It discloses the underlying endpoint (GET /api/v1/teams.json) and the shape of results, but says nothing about pagination behavior or result caps beyond what the schema's limit/offset already imply.

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

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

A single compact line: purpose and return fields first, endpoint last. 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?

With no output schema, the description usefully compensates by naming the returned fields (id, title, member count). Pagination is fully covered by the schema. The only minor gap is failing to note result-count or paging behavior for large team lists.

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 (limit, offset) are fully documented in the schema including defaults. 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 and resource ('List agent teams'), enumerates the returned fields (id, title, member count), and explains the downstream purpose: these are 'the ids for assigned_team_id'. An agent knows exactly what this returns and why it would call it, with no team-related sibling to confuse it with.

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

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

The phrase 'the ids for assigned_team_id' implies the calling context (resolving team IDs for assignment operations), but no explicit when-to-use/when-not or alternative is stated. Usage is inferable rather than prescribed.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavior not in the schema: result ordering ('newest first'). It says nothing about default page size, pagination envelope, or response shape beyond that.

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

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

Two tight sentences plus an endpoint reference; the capability statement is front-loaded and every clause carries information (scope, ordering, filter options, alternative tool, REST path).

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

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

For a read-only list tool with full schema coverage and no output schema, the description covers purpose, ordering, filtering, and tool routing. The main gap is lack of an explicit return-shape/pagination note, though the schema's limit/offset hints partially mitigate this.

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 five parameters are already documented in-schema (ids, role enum, limit, offset, include expansion). The description only restates role and id filtering at a high level, adding no format or interaction detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (list users), enumerates the four role types returned, and gives the ordering ('newest first') plus optional filters. It also names kayako_search as the different sibling, so an agent can distinguish this from get/search tools without opening schemas.

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

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

Explicitly routes the agent: 'To find a user by email or name use kayako_search,' which is a concrete when-to-use-an-alternative rule. It lacks an explicit when-not for the id/role filters, so it falls short of full 5-level 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 declare destructiveHint=true, and the description reinforces this with the 'WRITE:' marker plus a valuable behavioral distinction the annotations cannot convey: NOTE is visible only to agents while MAIL/TWITTER/FACEBOOK is a PUBLIC reply to the customer. It adds real context about visibility/side effects, though it omits auth/permission requirements and irreversibility details.

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:' operation type, then the NOTE vs public distinction, then auxiliary capabilities, ending with the raw endpoint. Dense and every clause carries routing or safety 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 12-param write tool with no output schema and only a destructiveHint annotation, the description supplies the essential routing (which channel to pick, where channel_id comes from) and the safety-critical visibility distinction, which is enough for an agent 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 67%, and the description compensates for the key gap: it explains that channel=NOTE needs no channel_id, that public channels need channel_id sourced from kayako_list_channels, and that status/priority/assignee can be set in the same call. It offers no clarification for lesser-used params (type_id, tags, cc), which the schema already covers.

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 (add a post to a case) and immediately splits the operation into two distinct behaviors: internal NOTE vs public reply. This clearly separates it from siblings like kayako_create_case and kayako_update_case, which create or mutate the case itself rather than adding a post.

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 tells the agent when to use NOTE (internal, no channel_id) vs MAIL/TWITTER/FACEBOOK (public reply), and points to kayako_list_channels to obtain channel_id. It does not, however, draw a boundary against kayako_update_case when the caller only wants to change status/priority/assignee, even though the description invites that overlap.

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

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

Annotations only declare readOnlyHint=true, so the description earns credit for adding the result shape (id, title, snippet, relevance, resource type), the fields='*' expansion behavior, and the hard 30-result cap. Pagination/offset behavior and what happens when results exceed 30 are not addressed, keeping 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?

Two sentences plus the backing endpoint, front-loaded with the scope statement, then return shape and limits. No filler and every clause carries information.

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

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

With no output schema, the description correctly compensates by naming the returned fields and the expansion option, and it documents the result cap. It is nearly complete for a search tool, missing only query-language guidance and what to do when the cap truncates results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description echoes the fields='*' trick and the 30-result ceiling that the schema already states, and its mapping of 'conversations (cases), users and organizations' lightly helps decode the USERS/ORGANIZATIONS/CONVERSATIONS enum for the resources parameter, but adds little genuinely new meaning.

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

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

States a specific verb and resource set: 'Unified search across conversations (cases), users and organizations.' The word 'unified' plus the resource list distinguishes it from siblings like kayako_list_cases, kayako_list_users and kayako_search_help_center. However it never explicitly contrasts itself with those list tools, leaving the differentiation implicit 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?

Usage is implied by 'unified search' — reach for this when you need free-text matching rather than enumeration. But there is no explicit when/when-not, and no mention of the sibling kayako_search_help_center, which covers the article domain and is the obvious alternative an agent might confuse this with.

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 goes beyond that by disclosing the return shape ({id, resource_type: 'article'}) and the underlying endpoint (GET /api/v1/helpcenter/search.json), which helps the agent plan its next call. It omits pagination behavior, though the schema's limit/offset params partially cover that.

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 scope and return shape come first, the follow-up tool second. Every clause earns its place with no redundancy.

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

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

With no output schema, the description helpfully sketches the return shape and the natural next step. Combined with full schema coverage of the five parameters, an agent has what it needs to invoke this correctly, though explicit guidance against sibling search/list tools would close the 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 every parameter (in, limit, query, locale, offset) already carries its own description with defaults and bounds. The description adds no parameter-level syntax or semantics, 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 (search) and resource scope (help center articles and/or public conversations), and clarifies the return type is references. It differentiates itself from list-style siblings like kayako_list_articles by being keyword-driven, but it never explicitly contrasts with the generic kayako_search sibling.

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 follow-up routing hint (read results with kayako_get_article), which is genuinely useful. However, it gives no explicit when-to-use guidance versus kayako_search or kayako_list_articles, so the agent must infer the search-vs-browse 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?

Adds real context beyond the thin annotations (only destructiveHint): the write nature, that no notification is sent to the customer, and that trashing is unsupported. It does not state whether omitted fields are preserved or replaced (a significant nuance for a PUT-style update) or what permissions are required, 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?

Front-loads the WRITE classification and keeps the payload-detail sentences tight; the raw endpoint reference (PUT /api/v1/cases/{id}.json) is defensible for traceability but is slightly redundant overhead.

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 with no output schema and sparse schema descriptions, the description covers the field surface, the no-notification behavior, and the excluded destructive operation. The main remaining gap is the partial-vs-full update semantics, which an agent would need to call this safely.

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, the description carries the load by naming every updatable field group (subject, requester, assignee, status, priority, type, brand, form, tags, custom fields) and clarifying that `tags` sets rather than appends the list. It leaves some ambiguity about assignee team/agent exclusivity and does not detail field_values, but it substantially compensates for the schema gap.

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: change a case's ...") and enumerates the exact mutable fields, which lets an agent map intent to tool without opening the schema. It also differentiates itself from the sibling kayako_add_case_tags and from reply-type tools via "Sends nothing to the customer."

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 append case to the alternative: "use kayako_add_case_tags to append," and rules out an unsupported operation ("Trashing is deliberately not exposed"). It also implicitly excludes customer-facing replies by stating nothing is sent to the customer.

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