Hide or unhide comments

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

Goes well beyond the annotations: annotations only say destructiveHint=false and idempotentHint=true, while the description explains *why* — the comment stays visible to its author and friends but not everyone else, nothing is destroyed. It also discloses partial-failure semantics ('each id gets its own outcome'), deleted-comment idempotency, and the exact token/scopes required (PAGE token, pages_manage_engagement, MODERATE task).

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?

Four sentences, front-loaded with the action and batch limit, then reversibility, then alternative, then failure/permission notes. The parenthetical `hidden:true`/`hidden:false` mapping is compact and 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 mutation tool with no output schema, it covers semantics, reversibility, partial failure, and auth. The one meaningful gap is that it never mentions the dry-run/apply workflow, so an agent must read the `apply` and `plan_id` schema descriptions to know a call may not actually write — acceptable given 100% coverage, but a sentence here would close the loop.

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 baseline is 3; the description still earns a bump by stating that each id returns its own outcome and by advising to split larger sweeps across calls rather than lowering maxItems. The `hidden` mapping and the 50-item cap are restated from the schema rather than adding new detail, and the apply/plan_id dry-run flow is left entirely to the schema.

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 verb pair (hide/unhide), the resource (comments), and a concrete batch bound (up to 50) in the first clause. It also distinguishes itself from the nearest sibling by name (facebook_delete_comment), so an agent can route correctly without opening either schema.

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 frames hiding as the reversible moderation verb and instructs 'prefer it over facebook_delete_comment', giving both the condition and the alternative. It also flags the batch-splitting rule for sweeps larger than 50, which is exactly the operational guidance an agent needs.

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