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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds substantial context beyond that: public-only posts, newest-first ordering, max count applied before filtering, sponsorable/dark_post semantics, and the missing_scope error with reconnect guidance. No annotation contradiction.

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 purpose and next-step handoff are front-loaded, and most sentences carry useful operational detail. However, the media_type enumeration and per-post field list are lengthy, and an output schema exists, so some of that detail is verbose rather than essential.

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 read-only, open-world listing tool with permission requirements, the description covers prerequisites, defaults, filtering limits, error handling, and the downstream workflow. Return-value details are also covered by the output schema, so nothing critical is missing.

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 0%, but the description compensates for all three parameters: count is capped at 100 before filtering, organization_urn defaults to the page linked to the ad account, and workspace is optional when only one workspace exists.

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 a specific verb and resource: published public posts of a LinkedIn company page, newest first. It also names the downstream sibling linkedin_create_ad_from_post and explains the post_urn handoff, so the agent can distinguish this listing tool from ad-creation 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?

Explicitly frames the use case: find a post for an ad and pass post_urn to linkedin_create_ad_from_post. It also gives default organization behavior and permission prerequisites, but does not explicitly state when not to use it or name alternative listing tools.

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