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

Beyond the readOnly/idempotent annotations, the description adds valuable behavioral detail: it returns the account owner's posts, requires the agent to choose the matching post and reuse result.id, and clarifies that the post ID must be the exact provider/Unipile ID, often base64-style for LinkedIn. This materially helps the agent understand the resolution workflow and what to do with the result. No contradiction with annotations is present.

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 front-loaded with the core purpose and then moves through the result contract, ID format, acquisition sources, and input exclusions in a logical, compact sequence. Every sentence carries actionable information and there is no filler or tautological repetition.

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 resolver with no output schema, the description gives a clear result contract ('Returns the account owner's posts; choose the matching post and reuse result.id'), the expected ID format, and the exact ID sources. The main gap is that the offset parameter is left unexplained, and the instagram_list_user_posts source is slightly surprising in a LinkedIn-specific tool, but overall the agent has enough to call and use the tool correctly.

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 only 50%: account_id is well documented in the schema, but offset has no description. The tool description does not compensate by explaining offset or otherwise enriching the parameters. The 'Never pass' guidance is helpful but concerns non-parameters, while offset's pagination semantics remain undocumented.

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 verb and resource: it resolves a user's descriptive phrase such as 'my latest post' into exact post IDs, and clearly scopes it to the account owner's posts. It distinguishes itself from sibling resolvers like linkedin_resolve_company, linkedin_resolve_person, and social_resolve_comment by naming the target ('my post') and the downstream actions it feeds (comments/reactions/edit/delete).

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 context for when to call the tool ('before comments/reactions/edit/delete') and strong input exclusions ('Never pass: post text, author user ID, URL unless a resolver tool explicitly accepts it'). It also tells the agent how to obtain valid IDs via linkedin_search_posts, linkedin_list_user_posts, and instagram_list_user_posts. However, it does not explicitly name an alternative for the case where an exact post ID is already known.

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