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

Annotations already establish the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description only needs to add context beyond that. It adds meaningful scoping ('available on the user's account') and cross-tool ID semantics, though it does not disclose details like pagination, empty-result behavior, or authentication requirements. Given the strong annotations, this is solid but not exhaustive.

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 main purpose is front-loaded, and the labeled sections for contract ID vs inbox ID are structurally clear. There is some redundancy—'contract.id' and 'Never pass: inbox_id' appear more than once—so it is slightly less concise than ideal, but every block carries important disambiguation value.

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 simple, read-only, zero-required-parameter list tool with no output schema, the description plus input schema covers everything an agent needs: what is listed, how to obtain the relevant IDs, what not to pass, and how the optional account_id should be handled. The sibling context also makes the tool's role in the broader LinkedIn workflow clear.

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% and the input schema already fully documents account_id, including the 'Nilyo never guesses' fallback behavior. The tool description's ID-related warnings concern contract_id/inbox_id values used by other tools, not this tool's own parameters, so the description adds no additional parameter semantics 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?

The description opens with a specific verb and resource: 'List LinkedIn premium contracts available on the user's account.' It clearly differentiates from linkedin_select_contract and linkedin_list_inboxes by emphasizing that contract.id is distinct from inbox_id and is the only valid value for contract_id.

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?

The description explicitly states when to use the returned data: 'contract.id is the ONLY value to pass as contract_id to linkedin_select_contract.' It also names the alternative for inbox IDs ('Obtain with: linkedin_list_inboxes -> inbox.id') and gives negative guidance ('Never pass: inbox_id, product name'), leaving no ambiguity about when this tool is appropriate.

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