list_conversations

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

Annotations already carry readOnly/idempotent/non-destructive, so the description is free to add genuinely new behaviour: the plan and scope requirement, mode-dependent meaning of limit, default 50/max 100, and the Meta reply-window caveat that a reply does not extend the window and it is not inferred from loaded messages. That last point is real domain behaviour an agent could otherwise get wrong; only return shape is left uncovered.

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 and organised around the two modes, with the plan requirement parenthesised rather than buried. Sentences are long and dense, and the trailing reply-window note takes three clauses, but no sentence is 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?

For a 10-parameter read tool with no output schema, the definition covers modes, defaults, mutually exclusive filters, access gating and the reply-window caveat. An agent could invoke it correctly; only the returned conversation/message field structure is unspecified, which is a modest gap given no output schema exists.

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%, so baseline is 3, but the description adds meaning the schema cannot express: limit counts conversations normally and messages when conversation_id is set, and other filters are invalid in single-conversation mode ('only workspace_id may be added'). That cross-parameter constraint is the most useful thing it contributes.

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 precise verb+resource and scope: 'Social inbox DM conversations for Instagram and Facebook Page inboxes', and immediately kills the obvious confusion by noting Threads has no DMs. The dual-mode behaviour (list vs single-conversation retrieval) is stated up front, so an agent can distinguish this from list_comments or manage_conversation.

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 partitions usage by argument: without conversation_id you list with filters and paging, with conversation_id you fetch one thread and its messages with only workspace_id addable. It also states the access prerequisite (Pro plan or higher plus posts:read). It stops short of naming competing siblings such as manage_conversation or list_comments to route away from.

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