Triage comments

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

Annotations already cover the safety profile (readOnly, non-destructive, idempotent), and the description adds genuine behavioral context beyond them: the Page's own comments are excluded, `pageReplied:null` signals a budget-exhausted or incomplete reply check, unreadable posts become notes and set `truncated`, and comment text/authors arrive as untrusted data in a labeled envelope. That last point is important agent-safety guidance not derivable from any structured field.

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 highest-value framing and information-dense throughout; the untrusted-content warning and the null/truncated caveats each justify their space. It is a single dense block with some nested parentheticals that slightly slows parsing, but 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?

With no output schema, the description usefully pre-empts the two surprising output states (`pageReplied:null`, `truncated` notes) an agent would otherwise misread. For a seven-parameter, zero-required read tool that is close to sufficient; only the interaction between `max_comments`, `posts`, and result truncation is left unexplained.

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 the schema already fully documents all seven parameters with defaults, bounds, and semantics. The description reinforces `status` values and `keywords` matching (case-insensitive substring, any-match) but adds no syntax beyond the schema, and omits `posts`, `max_comments`, `profile`, and `include_replies` entirely. Baseline 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?

Opens with a concrete framing ("A moderation queue in one call") and a specific resource (comments on the Page's most recent published posts), plus ordering (newest first). It is clearly distinguishable from a per-post comment lister by the aggregate-across-posts framing, though it never names facebook_list_comments directly, leaving that differentiation to inference.

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 operational context (moderation triage over recent posts) and explicitly routes follow-up actions to facebook_reply_to_comment, facebook_hide_comment, or facebook_private_reply. It also explains the default "unanswered" filter as the primary triage mode. It stops short of an explicit when-not or a named alternative for plain listing.

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