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

Annotations already indicate readOnlyHint=false, idempotentHint=false, but the description does not contradict them. It adds crucial context: the comment_urn is used directly as threadUrn, which implies the API will treat it as the thread identifier. It also implies a write operation by 'post a reply', which aligns with destructiveHint=false but not enough to flag. The description does not mention idempotency behavior, but that is covered by the idempotency_key parameter schema. No contradiction, and it adds value beyond 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 description is a single informative sentence that front-loads the primary action and immediately provides the critical mapping instruction. Every word adds value; there is no fluff or repetition of schema details. This is appropriately concise.

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 tool has an output schema, so return value details are covered there. The description covers the main purpose and the key parameter mapping, but it does not mention idempotency or any limitations beyond that. Given the complexity (only 4 params, no enums, simple operation), it is quite complete. However, a note about idempotency behavior might be useful, but the schema already explains that, so 4 is appropriate.

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 100%, so the schema already documents all parameters, including the idempotency_key's behavior in detail. The description adds extra meaning by clarifying that comment_urn is the comment_id from scrape_post and is used as threadUrn. This goes beyond the schema's simple 'URN of the comment' by specifying the source and direct usage, so it earns above baseline.

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 the action (post a reply), the resource (existing LinkedIn comment), and the direct parameter mapping (comment_id to comment_urn). It distinguishes from siblings like comment_post and send_message by specifying the target is a comment, not a post or message.

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 explicitly instructs to pass the comment_id returned by scrape_post as comment_urn, and states it is used directly as threadUrn. This gives precise when-to-use guidance and avoids ambiguity about which identifier to use. It does not explicitly say when not to use it, but the mapping instruction is strong enough.

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