hide_comment

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does convey that this is a mutating toggle operation (hide/unhide) and shows the HTTP method and endpoint, which helps. But it does not explicitly state side effects (e.g., whether hiding removes the comment from public view, whether it is reversible beyond toggling), authorization needs beyond 'your Page's post', or any rate-limit considerations. The disclosure is adequate for a simple toggle but not comprehensive.

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?

The description is a single front-loaded sentence with zero filler. It efficiently combines the action, resource, and the endpoint reference, making it easy to scan and understand. Every word contributes value.

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 simple two-parameter toggle tool with an output schema, the description is nearly complete: it states the action, the resource, and the endpoint pattern. The main omission is explicit routing guidance (when to use this vs. siblings) and any note on permissions, but those are secondary given the straightforward nature of the tool and the presence of an output schema for return values.

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 0%, so the description must compensate. The endpoint pattern 'POST /{comment-id}?is_hidden=...' provides a strong hint that comment_id maps to the comment path variable and hide likely maps to the is_hidden query parameter. The phrase 'Hide or unhide' implies the boolean hide parameter controls the toggle. However, the description does not explicitly document that hide=true means hide and hide=false means unhide, nor does it define comment_id format beyond the endpoint. Some meaning is added, but gaps remain.

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 clearly states a specific verb ('Hide or unhide') applied to a specific resource ('a comment on your Page's post'). It also includes the exact API endpoint pattern, which distinguishes this from siblings like delete_comment, get_comment, and publish_comment. An agent can identify what this tool does without opening the 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?

The description implies usage: you would call this when you want to change the visibility state of a comment on your Page's post. However, it offers no explicit guidance about when to choose this over alternatives (e.g., delete_comment for permanent removal, publish_comment for adding a new comment), and no exclusions or conditions are given. Usage context is present but not fully elaborated.

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