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

The annotations already declare readOnlyHint=true and destructiveHint=false, and "Read-only" is consistent with them. Beyond that, the description discloses ordering ("newest page first"), pagination direction ("go back" via before), and per-message attribution ("marked as the member's or the other person's") – real behavioral context the annotations do not carry. It does not mention what happens at the end of a thread when no earlier page exists, which would be the last useful 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?

Three short sentences, front-loaded with the core action, then the two return modes in the order an agent would encounter them, then a one-word safety marker. No filler or duplicated schema 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 takes on return-shape disclosure and does it well for both the inbox and thread modes, including unread state and message attribution. The only gap is that the person and project parameters, which change whose account and workspace the read runs against, are not surfaced at all.

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 defines before, conversation, person and project in detail; baseline is 3. The description reinforces the meaning of conversation (inbox vs thread) and the direction of before ("earlier message id ... to go back"), but says nothing about person or project, leaving the impersonation and workspace scoping 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 gives a specific verb and resource ("Read the member's own Connections messages") and immediately splits the tool into its two concrete modes: inbox when no conversation id is supplied, thread when one is. This cleanly separates it from the write siblings connections_message_reply and connections_message_start without requiring the reader to open 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?

"With no conversation id it returns the inbox" and "With one, it returns that conversation's messages" make the selection condition between the two modes explicit, and the pagination instruction ("pass the earlier message id as before to go back") tells the agent how to continue. It stops short of naming sibling tools such as connections_message_reply for the follow-up write action, so routing is left partly to inference.

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