instagram_comment_media

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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds meaningful behavior: 'Publicly visible immediately' and the requirement for INSTAGRAM_ALLOW_WRITES=true. It also discloses the return structure. These go beyond the annotations, which already indicate a non-read operation, giving the agent practical expectations about effects and prerequisites.

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 compact and well-organized: a lead sentence with the primary action, two short warning lines about visibility and permission, then a clear Args/Returns breakdown. Every section earns its place, and the essential constraints are front-loaded. No wasted words or redundant elaboration.

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?

The description covers the core essentials: what it does, a critical prerequisite (write permission), a human-confirmation requirement, and return values. It does not mention error cases or rate limits, but the output schema (declared present) and annotations handle some of that, and the absence of extreme detail is acceptable for a straightforward write action. Missing nuances like idempotency are already covered by idempotentHint=false.

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?

The input schema has 100% descriptor coverage: 'Comment body,' 'Post URL, shortcode or media id,' and 'Comment id to reply to, from instagram_get_media_comments.' The description's Args section largely mirrors the schema, adding only the phrase 'Reply to this comment instead of the post' for replied_to_comment_id, which clarifies its effect but doesn't add new semantics beyond the schema. The description does not introduce format details beyond 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?

The description opens with 'Post a comment on a post, or a reply to an existing comment,' which clearly specifies the verb (post/reply), resource (comment on post/comment), and the two distinct use cases. This distinguishes it from other write tools like instagram_like_media or instagram_upload_photo, and there is no sibling comment tool, so purpose is unambiguous.

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 provides explicit context: 'Requires INSTAGRAM_ALLOW_WRITES=true' and instructs to 'Confirm the wording with the person you are working for first.' It does not explicitly name alternatives or when not to use, but since it's the only comment tool, the guidance is sufficient. It could improve by mentioning to fetch comment IDs via instagram_get_media_comments for replies, but that is inferred from the reply parameter.

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