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

The annotations (readOnlyHint: true, destructiveHint: false) are consistent with a read-only analytics tool. The description discloses behavioral details such as null postId for discovered posts, metric nulls for unsupported platforms, and sort behavior (newest first for PUBLISHED_AT), fully informing the agent of side effects and limitations.

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 dense but efficient, using semicolons to separate related ideas. It packs essential information (scope, sorting, pagination, platform caveats) without redundancy or filler, making it easy to parse.

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?

It fully describes the return shape (posts array, total, page, limit, hasMore) and per-post fields, including metrics and platform-specific null behavior. Edge cases like unsupported platforms and pending LinkedIn analytics are covered, so an agent knows exactly what to expect.

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?

All six parameters have explicit descriptions in the schema, covering meaning, defaults, and constraints. The overall description adds context, such as the comparison window for 'from' and platform restriction semantics, enriching the schema with operational details.

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 ('Per-post metrics for posts published inside the window'), highlights typical use cases ('top posts', 'which post got the most comments'), and clearly distinguishes it from list_post_results by stating 'Not for publishing status'. This makes the tool's purpose unmistakable.

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 explicitly names the alternative for publishing status ('use list_post_results for that') and explains when to use this tool (for per-post analytics). It also provides practical filtering guidance (platforms with no analytics are ignored, LinkedIn pending approval), leaving no ambiguity about when to invoke it.

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