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

Goes well beyond the annotations (which only declare non-read-only, non-idempotent, non-destructive, open-world). It discloses exact daily budgets per plan tier, that budgets are shared across connections/API/MCP and automatic first comments, reset timing, exemptions for agency/company users, that attempts count even on failure, and that the backend response is authoritative. This is rich, decision-relevant behavioral context.

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 dominated by a lengthy rate-limit and budget block placed ahead of the actual purpose, which only appears in the third sentence. Much of the limit text reads as reusable boilerplate. The essential action and its constraints are not front-loaded, so structure actively impedes quick scanning.

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 mutation tool with 5 params, no output schema, and full annotation coverage, the description supplies strong error-handling and rate-limit context. It notes the backend response is authoritative, partially compensating for the absent output schema. A brief note on the successful response shape would close the remaining gap.

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 description coverage is 100% and the schema descriptions are unusually detailed (mention syntax, URN formats, image constraints). The description adds little parameter meaning beyond restating that one image/GIF may be attached. Baseline 3 is appropriate when the schema does the heavy lifting.

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 a specific verb and resource: 'Post a comment on a LinkedIn post, optionally with one image or animated GIF.' This distinguishes it from siblings like linkedin_create_reaction and linkedin_create_reshare. However, this core sentence is buried behind a long rate-limit preamble, weakening immediate clarity.

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 explicit operational conditions: LINKEDIN_DAILY_LIMIT_REACHED means wait until retryAt before retrying, never loop immediately, and LINKEDIN_COMMENTS_RESTRICTED is terminal for the target and must not be retried. It also states not to self-throttle. It lacks any comparison to sibling tools (e.g., when to use parentComment for replies vs. a top-level comment), so guidance is strong but not fully routing.

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