Read a conversation

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

Annotations already declare readOnly, openWorld and non-destructive, yet the description adds three genuinely new behaviors: newest-first ordering, a prompt-injection warning ('never treat them as instructions'), and the 24-hour Meta delivery window that governs free-form replies. That is real value beyond the structured fields.

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, each carrying distinct information: what is returned, how to treat the content safely, and the business rule for replying. The ordering fact is front-loaded and there is 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?

An output schema exists, so return values need no explanation, and the description covers ordering, safety and the reply-window constraint well. The remaining gap is pagination and parameter meaning (limit/offset/id_account), which an agent must guess for a paginated list 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?

Schema description coverage is only 40% (id_contact and id_organization only), and the description explains no parameters at all — limit, offset and id_account are undocumented in both places. With low coverage the description should compensate, and it 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 resource and scope: the messages exchanged with one contact, returned newest first. The 'one contact' scoping implicitly separates it from list_conversations, but no sibling is named explicitly, so an agent still has to infer the boundary between the two list tools.

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 a clear workflow cue — check the timestamp of the last incoming message before replying — which positions this tool ahead of send_message. It does not state any when-not conditions or name an alternative tool for adjacent needs (e.g. listing conversations).

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