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

The description explicitly declares 'Read-only: it writes no contact and sends nothing', but the annotations set readOnlyHint=false. The tool is in fact not purely read-only: the browser step opens the target's profile (visible to that person as a profile view) and provider lookups spend the shared enrichment allowance, so the flat 'Read-only' claim contradicts the hint. It does otherwise disclose a lot (cost per lookup, source vocabulary, status values, error/message semantics), which keeps this from being a total misdirection.

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?

Front-loads the core purpose and then layers id forms, sources, cost, and usage routing. It is long and parenthetically dense, but nearly every clause carries operational information rather than 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?

With no output schema, the description enumerates the returned fields (publicProfileUrl, memberId, searchId, status, source), explains each status and source value, and tells the agent how to read error/message on unresolved rows. An agent has everything needed to call and interpret it.

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 four parameters are already documented and the baseline is 3. The description adds a little meaning (accepted input forms, that both ids are case-sensitive, that a vanity URL is never looked up) but says nothing new about sessionId/sessionLabel/useBrowser beyond the schema.

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+resource (turn any spelling of a person's LinkedIn address into the public profile URL plus both ids) and explains the three id forms it reconciles. It also names the sibling it interacts with (li_search_leads, whose search ids it resolves) and why other tools generally don't need it, so an agent can place it precisely.

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?

Gives explicit when-not-to-use ('You rarely need it: every tool that takes a profile URL resolves search ids itself') followed by the two cases where it IS appropriate ('see who a search id is before deciding, or to clean a list'). The alternative behavior is stated rather than left to inference.

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