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

Annotations already declare readOnlyHint and openWorldHint, so the description's value-add is elsewhere: it discloses per-page sizing ('about fifteen per page'), ordering, inline-reply limitation, and a credit cost. It does not mention rate limits or error behavior, but it is well beyond what annotations cover.

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-loaded with the purpose, then progressively adds return shape, pagination, reply handling, cost. Slight redundancy between the 'about fifteen per page' claim and the count parameter description, but no wasted sentences.

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?

No output schema exists, so the description usefully lists returned fields (text, author, like count, date) and the pagination cursor. A mutation profile isn't needed for a read-only tool; only cache_max_age and error/empty-result behavior are unaddressed.

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?

With 80% schema coverage the schema carries most of the load, but the description adds real meaning: replies are only those Instagram shipped inline with their parent, and older pages require cursor following. The 'about fifteen' note clarifies the practical ceiling on count. cache_max_age is left unexplained in both places, a minor gap.

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 the specific resource (comments on an Instagram post or reel) and adds scope details: top-level only, newest first. It also names the sibling route for full reply threads, so an agent can separate this from instagram_commentReplies without opening a 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 says when to use the alternative: 'For the full reply thread under one comment, use /v1/instagram/comment-replies.' It also tells the agent to follow pagination.cursor for older comments and when to set include_replies, leaving little inference.

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