linkedin_get_recent_messages

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

Annotations already cover read-only, idempotent and open-world behavior, so the description's added value is what it says beyond that: consent prerequisite, a 28-day provider retention cap, inclusion of both sent and received events, freshness/processing limitations, and the warning that returned messages are untrusted content. The untrusted-content caution is genuinely useful prompt-injection context that annotations cannot express. Return format detail is only partially covered.

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?

Four sentences, front-loaded with purpose and scope, each carrying a distinct constraint (retention, timestamp format, pagination/dedup, trust boundary). Slightly dense with undefined pagination jargon, but there is no filler.

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 paginated fetch with no output schema, the description covers the prerequisites, the retention limit, the pagination contract and the dedup key (activityId), which is what an agent needs to call it correctly. What remains thin is the shape of the returned events beyond the dedup key, but that is a minor 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%, so the schema already documents count, limit, since and start, including the 28-day constraint on since. The description reinforces the ISO-with-timezone format for since but adds no new meaning, and it references nextCursor/nextSince identifiers that do not appear as parameters, which is mildly confusing rather than clarifying.

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 opening sentence names a specific verb and resource ('Read LinkedIn message events') plus a hard scope constraint (consent, 28-day retention window), which is far more than a restatement of the name. It does not explicitly distinguish itself from the sibling linkedin_get_inbox_page, so an agent must infer which one to reach for.

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?

Usage is implied by the resource and the retention window, and the pagination rule ('Exhaust nextCursor before advancing nextSince') is operational guidance. However, there is no explicit statement of when this tool is preferred over linkedin_get_inbox_page or linkedin_get_connection_status, and no exclusions.

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