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

Annotations only declare readOnlyHint, so the description carries real behavioral weight and does so: truncation is detectable via messagesReturned vs totalMessages, system entries are excluded and not counted in totalMessages, and tag groups are unnamed internal ids. The attachment semantics are unusually strong — url is a time-limited per-call link while resourceId is the stable identity, and ticketDetails.url is the permanent human-facing link.

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 truncation guidance is correctly front-loaded and nearly every clause carries substantive information, but the whole definition is a single unbroken block that runs well past what a two-parameter tool needs, and the senderRole explanation is a lengthy detour buried mid-paragraph.

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 must explain the return shape, and it does so thoroughly: message envelope, senderRole taxonomy, attachment object shape, and the two distinct URL types. Given the tool's complexity as a combined metadata-plus-messages read, nothing an agent needs to interpret the response 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% for both required parameters, so ticketId and productId are already fully documented in the schema, including where to source the ids. The description adds no syntax, format, or edge-case guidance for either parameter, which is the expected baseline 3 when the schema does the work.

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 opening sentence states a specific verb and resource ('Get ticket metadata plus the newest conversation messages') and immediately scopes it as a 'most recent window' rather than full history. The sibling it could be confused with, getTicketMessagesBatch, is named and distinguished in the same sentence, 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?

It names two alternatives with their selecting conditions: getTicketMessagesBatch when full histories are needed, and getTicketAttachment when an image attachment must be viewed over MCP. It stops short of a full when-not-to-use statement (e.g., no guidance on when listTickets is the better starting point), which keeps it just below the top score.

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