Activity Since

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

Explains behavior beyond annotations: local high-water mark per Page, first call defaulting to last 24h, non-advancement when mark_seen is false, and that a truncated section keeps its mark so nothing is skipped. This also justifies the idempotentHint:false despite readOnlyHint:true, and adds a prompt-injection warning about untrusted comment/message content.

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-loads what the tool returns, then the high-water-mark mechanics, then the truncation caveat, then the safety envelope and next-step routing. Every sentence carries distinct operational information with 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?

For a 7-parameter, multi-section read tool with no output schema, the description covers return sections, the `truncated:true` signal, mark advancement, first-call window, and trust boundaries for user content. Remaining details (e.g., exact envelope fields) are the main omission but not operationally blocking.

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 71%, and the description adds real semantics for the key params: `since` omission semantics, `mark_seen:false` peek behavior, and the budget/truncation meaning around `max_comments`. It does not add meaning for `posts`, `profile`, or the two include_* toggles beyond their names.

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: 'What is new on a Page since a point in time, in one call: new comments (and replies) on the most recent published posts, and Messenger conversations updated since then or still unread.' This distinguishes it from the broad listing siblings (facebook_list_comments, facebook_list_conversations) by its incremental, cross-section nature.

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 clear operational guidance: omit `since` to resume from the stored high-water mark, `mark_seen:false` to peek without advancing, and routes follow-ups to facebook_reply_to_comment / facebook_send_message. It stops short of naming the alternative full-history listing tools or when to prefer them, so no explicit when-not-to-use clause.

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