The brand’s Messenger and Instagram DM threads

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

Annotations already declare readOnlyHint=true and destructiveHint=false plus openWorldHint=true, and the description never contradicts them. Beyond that it adds substantial operational disclosure: it reads inbox AND message requests by default, each thread is labeled with its folder origin, an empty list is explicitly NOT 'nobody messaged you' (it names measured causes including an app-level Instagram capability), the warning not to tell users to toggle Instagram settings, and the 'Read-only, 0 credits' cost note. This is deep beyond-annotation behavioral context.

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?

Every sentence carries operational value, but the description is a single dense wall of text with ALL-CAPS emphasis that makes it shouty and harder to skim. The empty-list and app-capability warnings justify some length, but phrasing like 'one question to a person, two edges to Meta' is cryptic, and the content could be tightened and sectioned without losing information.

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 tool with four optional parameters spanning two surfaces and subtle message-request semantics, this description is remarkably complete: it explains defaults, per-thread provenance, the empty-list failure mode, the unrecoverable app-capability cause, cost, and safety. Despite having no output schema, it conveys the return shape (who, when, counts, unread, folder origin) clearly. Nothing an agent needs to call it correctly 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 description coverage is 100%, so the baseline is 3 — and the schema already documents the critical folder-refusal behavior, the platform enum meaning, and the limit/pageId semantics. The description reinforces the platform 'both surfaces / two edges to Meta' idea and the folder default, but most of the parameter value lives in the schema. It adds marginal framing rather than new semantic content, so 3 is appropriate.

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 states a specific verb and resource — listing DM threads across Facebook Page and Instagram, with the exact fields returned (who wrote, last-write time, message count, unread count). It is clearly distinguishable from siblings like read_meta_conversation (reads one thread) and the other DM-listing tools (list_telegram_dms, list_x_dms, list_inbox), and the opening 'THIS IS WHERE THE BUYING QUESTION GETS ASKED' gives the agent a concrete sense of what the data is for.

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?

The description explicitly routes to the one-thread alternative ('Read one thread with read_meta_conversation') and explains the platform narrow-vs-both choice and the folder default ('Omit to read inbox + other'). It does not, however, contrast this tool with the generic sibling list_inbox or spell out a when-not-to-use condition beyond the empty-list caution, so the exclusions are implied rather than fully explicit.

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