Turn comments on or off

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

Annotations already declare the mutation is non-destructive and idempotent, so the bar is lower. The description still adds genuinely useful behavior beyond them: the effect is publicly visible to everyone and therefore requires user confirmation before executing. It omits any mention of permission requirements or what the response contains, but the confirm-first constraint is the most important behavioral detail an agent needs.

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?

Three short sentences with the action and its most important consequence front-loaded. The trailing parenthetical that captions cannot be edited via Meta's API is a non-sequitur for a comment toggle and slightly dilutes focus, though it is short enough not to be costly.

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?

Four parameters, two required, no output schema, and annotations covering safety and idempotency. The description covers what changes, who can see it, and the confirmation gate, which is sufficient for correct invocation. It could note whether the toggle is reversible or what a post with disabled comments looks like, but nothing critical 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 coverage is 50% — account and confirmation_token are documented, while media_id and enabled are not. The description partially compensates by linking 'one of your posts' to media_id and the confirmation requirement to confirmation_token, and 'enable or disable' makes the boolean obvious. It adds some meaning but leaves media_id's exact form (media ID vs shortcode) unstated.

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 and resource: 'Enable or disable comments on one of your posts.' An agent immediately knows this is a post-level comment toggle. It does not, however, distinguish itself from siblings like hide_comment or delete_comment, which act on individual comments — that distinction is left 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?

The line 'Visible to everyone, so the user confirms first' implies a two-step confirmation workflow, which is real when-to-use guidance for the confirmation_token flow. But there is no explicit statement of when to pick this over hide_comment or why one would toggle comments off entirely, and no prerequisites for media ownership are given.

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