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

Annotations already declare readOnly/non-destructive/openWorld=false, and the description goes well beyond them: per-mode sort order (oldest first for event, newest first for thread and list), the 100-message cap per conversation, the meaning of `has_more`, and how to backfill older messages. This is exactly the behavioral context annotations cannot express.

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 one-line purpose, then a bulleted mode list with the shared paging rule last. Dense but every clause carries information an agent needs; nothing is repeated from the schema or annotations.

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 5-param, zero-required, output-schema-backed read tool, the description covers mode selection, ordering, paging, and truncation behavior. Return shape is intentionally left to the output schema, which is the right division of labor.

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 0%, and the description does give meaning to all five parameters (event as workout/trn_/ptrn_ handle, thread as conversation handle, limit with max 100, starting_after as last returned id, unread_only for filtering). However, it omits the default `limit` of 20 and doesn't restate types or that all params are optional, so the schema still carries some weight the prose does 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 the messages between a coach and athletes') and immediately enumerates the three concrete modes (event, thread, neither), so an agent knows exactly what each invocation returns. No sibling tool in the list covers conversations, and the description makes the boundary obvious.

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 'three uses, one at a time' and gives the selecting condition for each mode, including where the `ptrn_…` handle should come from (get_calendar). It also routes the agent to `thread` + `starting_after` when `has_more` is set, which is genuine when-to-use guidance.

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