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.