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

With readOnly/idempotent already covered by annotations, the description still adds substantive behavior: results are page-based with a total, dates are interpreted in the workspace time zone with inclusive To bounds and an echo of the exact instants in dateRange, and names/addresses/domains/notes are wrapped as untrusted content. That trust-handling disclosure is exactly the kind of context annotations cannot express.

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 is front-loaded well, but roughly half the text restates parameter behavior already documented at 100% schema coverage (query, tagSlug, listId, docId, projectId, createdFrom/createdTo, seenFrom/seenTo), and the trailing sentence about titles and summaries from document authors is only tangentially relevant to a contacts list. It reads as dense rather than trimmed.

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?

There is no output schema, and the description compensates fully by enumerating row contents (name, address, domain, first/last seen, document and project counts, visits, tags, team note), noting identity: true on name/email, and covering pagination via total. An agent has everything needed to call it and interpret the response.

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 coverage is 100%, so the baseline is 3; the description goes beyond it by stating that query also hits the team's note and the self-provided name, and by explaining the date grammar (bare date = whole day in workspace TZ, To inclusive, since is the legacy alias of seenFrom). These are semantics the schema does not carry, though a few filter descriptions (tagSlug, listId, docId) are simply restated.

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 gives a specific verb plus resource and, unusually, defines the resource's scope: 'everyone who introduced themselves on a link, read while signed in, asked to download a file or dropped one in a request inbox', one row per person per workspace. It also names the detail sibling (lnkdrp_get_contact), so an agent can distinguish the list operation from the single-record operation immediately.

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 makes the list-vs-detail split explicit ('one contact's full note and history come from lnkdrp_get_contact') and enumerates which filter each parameter serves, which is effectively guidance on how to narrow. It stops short of stating explicit when-not-to-use conditions (e.g. bulk export limits, or that unfiltered listing on large workspaces should be paged carefully).

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