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

Annotations already indicate destructiveHint=true and readOnlyHint=false, covering the side-effect nature. The description adds 'on behalf of the user' and 'only when the user has asked,' which are useful behavioral cues. However, it does not mention potential irreversibility, permission requirements, or rate limits. Given the annotations cover the core safety profile, the description adds moderate value.

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?

Two sentences with no filler. The purpose is stated first, followed by a clear usage condition. Every word earns its place, and the key constraint (use after reading, only on user request) is front-loaded.

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 straightforward write operation with no output schema, the description covers the essential aspects: what it does, when to use it, and the requirement for post_id. It omits error conditions or prerequisites, but these are not critical for a simple comment action. The schema handles parameter details adequately for most cases.

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 description does not elaborate on any parameters. Schema coverage is 67% (post_id and account_id have descriptions, text does not). The description does not compensate for the undocumented 'text' parameter or add any additional semantic clarity. It merely restates that post_id is required, which is already in the 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 states a specific action 'Publish a comment/reply on a LinkedIn post' with a clear resource. It distinguishes from siblings like linkedin_create_post (which creates a new post) and linkedin_reply_to_comment (which replies to a comment), though it doesn't explicitly name them. The title 'Comment on post' reinforces the intent, making the purpose 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?

Provides explicit guidance: 'Use after reading the post/comments and only when the user has asked to publish the final reply.' This tells the agent when to invoke it and implies it should not be used prematurely or without user consent. It does not explicitly mention alternatives, but the 'after reading' context effectively sets the appropriate trigger.

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