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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the post must already be resolved, IDs must be exact and scoped, and LinkedIn IDs often use base64-style formatting. No contradiction with annotations.

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 core purpose is front-loaded, which is good. However, the Post ID guidance is duplicated in the description and schema, 'Never pass' appears twice, and the comment-ID paragraph is somewhat convoluted. It could be tighter and better structured as bullets.

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?

There is no output schema, so the description must carry the burden of saying what the tool returns. It says comments are listed and maps to comment.id, but it does not state which fields are returned (e.g., author info needed to identify Sarah's comment) or how offset/pagination behaves. The upstream resolver references are helpful but leave gaps.

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 67%; post_id and account_id are described in the schema, while offset is not. The description adds provider-specific detail for post_id and names concrete resolver chains (linkedin_search_posts -> result.id), but it largely repeats the schema's post_id wording and does not explain offset semantics.

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 a specific action: 'List comments for an already-resolved post', and states the goal of mapping a human reference like 'the comment from Sarah' to an exact comment_id before reply/react/edit/delete. This distinguishes it from comment mutation tools such as social_delete_comment and social_update_comment, though it does not explicitly contrast with the platform-specific list tools.

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?

It gives a clear precondition ('First resolve post_id') and a clear use window ('before replying/reacting/editing/deleting'). It also provides strong negative guidance: never pass post text, author user ID, or URL unless a resolver explicitly accepts it. It stops short of explicitly naming when to prefer an alternative tool.

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