LinkMCP: hosted LinkedIn MCP server

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

Annotations already declare read-only, idempotent, open-world, non-destructive, so safety is covered. The description adds genuinely useful behavior the annotations cannot express: expected hit rates (~2 in 3 with company_domain, ~1 in 4 with company_name only) and the high frequency of no-result, which shapes how an agent should plan around failure.

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, each carrying distinct information: purpose, prerequisite sibling, accuracy expectations, and the validation alternative. Purpose is front-loaded and there is no redundant restatement of the name or title.

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, so the description should ideally clarify the shape of a hit versus a miss, and it only implies this via 'No result is common'. Otherwise it covers prerequisites, alternatives, accuracy expectations, and failure handling adequately for a four-parameter lookup tool.

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 and the schema already defines all four fields. The description earns extra credit by quantifying the accuracy difference between company_domain and company_name, giving the agent a reason to prefer one optional parameter over the other rather than just repeating the schema's 'Recommended for best accuracy'.

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 and resource (find a person's work email) plus the inputs it keys on (name and company), and the example use cases (prospect or candidate) frame it concretely. It is clearly separable from siblings like validate_email and linkedin_get_profile, both of which are named.

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?

Explicitly routes the agent: use linkedin_get_profile first when name/company are missing, and use validate_email when an address is already in hand. It also warns that a null result is normal and forbids guessing addresses, which is an explicit when-not-to-do-something instruction.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds the constraint that it resolves exactly one person and accepts a single identifier, but says nothing about what happens when no mobile number is found, hit rates, or any rate limits.

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?

Three short sentences, front-loaded with the operation and its scope, then the identifier options. Every sentence carries information and 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 two-parameter lookup with full schema coverage and rich annotations, the description is nearly complete. The one gap is the absence of an output schema combined with no mention of return semantics, such as what the agent gets when the person is identified but no mobile number exists.

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% and both parameters carry examples, so the baseline is 3. The description adds meaning the schema does not: with 0 required parameters, it clarifies that exactly one identifier is needed and that either the LinkedIn profile or the email alone suffices.

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 and resource ('Find the mobile phone number') plus scope ('of one person'), which cleanly separates it from lookup siblings like find_email and validate_email. It never names an alternative tool explicitly, so the differentiation is implicit in the resource rather than spelled out.

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 tells the agent which identifiers are accepted and that 'one identifier is enough', which is real usage guidance, but it gives no when-to-use/when-not-to-use framing relative to find_email or the other person-lookup siblings. Usage is implied by the resource name rather than stated.

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

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

With readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false already declared, the description still adds genuinely useful behavior: capped batch size, per-item result objects, and the fact that one failure does not abort the remaining items. That partial-failure contract is exactly the kind of detail 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?

Two compact sentences with no filler, and the batching scope is front-loaded ahead of the error-handling note. 'Slim' is the only mildly opaque term, but it usefully signals that profiles are trimmed rather than complete.

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 single-parameter, read-only, no-output-schema tool whose safety profile is fully covered by annotations, the description supplies the two things the schema cannot: batch cap and partial-failure return semantics. It does not describe what fields a 'slim' company profile contains, which is the only real 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 coverage is 100% and the single 'identifiers' parameter already documents accepted forms (URLs, slugs, numeric IDs) and the 1-10 range, so the schema carries the load. The description's 'up to 10' merely duplicates the schema's maxItems, adding no new parameter meaning — baseline 3 is appropriate.

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 and resource ('Fetch ... LinkedIn company profiles') plus the batching scope ('in bulk, up to 10'), which separates it from the single-record linkedin_get_company and from the person-oriented linkedin_bulk_get_profiles. It stops short of naming those siblings explicitly, so the distinction must be inferred from the word 'company'.

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?

There is no statement of when to choose this over linkedin_get_company for a single lookup, and no prerequisites or exclusions. 'In bulk' restates the purpose rather than providing routing guidance, so an agent gets no help deciding between the bulk and single variants.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the description's added value is the cost model ('one profile lookup each'), the detail-level output tradeoff, and the critical error-handling contract ('Returns per-item results and never stops on the first error'). That failure-mode disclosure is exactly the kind of trait an agent needs and the 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?

Front-loaded with purpose and limit, then detail modes, then cost, then exclusions, then error behavior - a logical ordering. It is denser than strictly necessary (the detail definition is repeated in the schema), but each sentence carries distinct information.

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 compensates by enumerating what each detail mode returns and by specifying the partial-success error semantics. Nothing an agent needs to call it correctly is missing, though response shape for per-item errors (error object fields) remains unspecified.

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 enum for 'detail' is documented in both the schema and the description with essentially the same content. The description adds cost equivalency and a pointer to linkedin_get_profile for the 'full' shape, but no new syntax or identifier-format detail beyond the schema, so the baseline 3 applies.

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 and resource ('Fetch LinkedIn profiles in bulk (up to 10)') and immediately distinguishes itself from the single-profile sibling by defining both detail modes. The scope (bulk, max 10, cost per profile) is unambiguous and an agent can pick it apart from linkedin_get_profile without opening either schema.

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 clear routing conditions: use this for 1-10 profile lookups at the same cost as linkedin_get_profile, and use linkedin_get_company when company details are needed. It stops short of saying when a single call is preferable to bulk (e.g. for one identifier), so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the agent knows this is a public, non-idempotent write. The description adds that mention identifiers are auto-resolved, which is useful context, but it never states that the comment is publicly visible, irreversible, or subject to platform rate limits — the exact risks an agent should weigh before a destructive public write.

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?

Three short sentences, front-loaded with the primary action, then capability scope, then the mention-resolution note. No filler, though the final sentence partially duplicates the schema's 'Automatically resolved' wording rather than earning new information.

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 destructive, multi-parameter write with no output schema, the description covers what the tool does and its two special modes, but says nothing about the result (e.g. whether the created comment ID is returned) or the visibility/permanence of the effect. It is adequate but leaves the post-call expectations to inference.

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 every parameter is already documented in the schema (including the {{0}} placeholder convention, identifier formats, comment_id for threading, and content_check semantics). The description largely restates what the schema says about URL/slug/URN resolution. Baseline 3 is appropriate when the schema does the heavy lifting.

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 and resource ('Comment on a LinkedIn post') and immediately scopes the capability with threaded replies and @mentions. An agent can distinguish this from linkedin_create_post, linkedin_react_to_post and linkedin_get_post_comments without opening the schema.

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 verb — use this to post a comment — and the mention/reply sentences hint at the threaded variant, but there is no explicit 'use this instead of X' guidance or when-not condition. The description never names a sibling tool (e.g. linkedin_create_post for top-level posts, linkedin_react_to_post for reactions).

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description itself only restates capabilities and does not add behavioral context such as irreversibility of publishing, visibility/audience consequences, or rate limits; the richer behavioral notes (content_check strictness, server-side image fetching, link-preview fallback) live in the schema rather than the description.

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?

A single front-loaded sentence naming the action first, followed by a compact capability list. No filler, no redundancy, and the most important information (create a post) leads.

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 7-parameter mutation tool with no output schema, the description covers the main content modes but omits what the call returns (e.g. post ID/URL) and any failure modes or permission requirements. Annotations plus the fully documented schema carry most of the load, leaving this adequate but not complete.

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 every parameter in detail (character limits, mention placeholder syntax, page posting, content_check modes). The description adds nothing beyond what the schema provides, so the baseline 3 applies.

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 ('Create a LinkedIn post') and then enumerates the supported content modes (text, images, mentions, link cards, reposts). This clearly separates it from siblings like linkedin_comment_on_post and linkedin_react_to_post, which act on existing posts rather than producing new ones.

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 only implied: the capability list hints at when to reach for this tool (multi-modal publishing, reposting), and the as_page parameter notes 'Omit it to post as yourself.' There is no explicit when-to-use/when-not guidance, no mention of prerequisites (e.g. needing a connection/page admin), and no named alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description adds real operational context beyond them: a rate limit of at most 3 name-based LinkedIn company searches per minute per account. It also discloses the fallback behavior (a name returns a match when clear, otherwise a short candidate list) and the slug-mismatch pitfall, which an agent could not infer from annotations.

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?

It is front-loaded with purpose, then usage exclusions, then parameter guidance, then pacing — a logical order. It is somewhat long for a two-parameter tool, and the "one at a time" instruction partially repeats the pacing sentence, costing a point.

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, so the description carries the burden and does so: it names the fields returned and explains the variable-shape case (single match vs. candidate list). Combined with the rate-limit and input-selection guidance, an agent has everything needed to call this 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 coverage is 100% and the schema already states mutual exclusivity, so the baseline is 3. The description goes further by explaining why to prefer `name` over guessing a slug ("LinkedIn slugs often differ from the name") and what each mode returns, adding genuine decision value rather than restating types.

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 uses a specific verb and resource ("Get a company's LinkedIn page") and enumerates the returned attributes (website, industry, size, headquarters, follower count). It also draws an explicit boundary against list/search behavior ("does not search for lists of companies by industry or location"), which separates it from siblings like linkedin_search_sales_navigator or linkedin_bulk_get_companies.

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 names the concrete use case ("research one company, for example before a sales call") and states when not to use it (list-by-industry/location searching). It further routes the agent between the two input modes and instructs looking up by name one at a time, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real value by disclosing the ~30-post cap per call and roughly what each post contains (text, engagement counts, URL), which matters because there is no output schema to fall back on.

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?

Two sentences, no filler, and the core action and identifier forms are front-loaded before the return summary. Every clause carries information.

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 does the necessary minimum by sketching the return shape and the per-call cap. Pagination is handled by the cursor field's own schema text, so the remaining gap is only the absence of explicit sibling routing.

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 schema already documents both parameters in detail. The description restates the three accepted identifier formats, which duplicates the identifier field's schema text without adding syntax or validation nuance, and it never mentions the cursor parameter.

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 and resource ('Get a company's recent LinkedIn posts') plus the identifier forms accepted, which is far more than a restated title. It stops short of explicitly distinguishing itself from the closest siblings (linkedin_get_person_posts, linkedin_get_company), leaving that inference to the agent.

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?

There is no when-to-use or when-not-to-use guidance, and no named alternative. The agent must infer from the name alone that company posts are not person posts and that linkedin_get_company is the route for company metadata rather than content.

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

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

Annotations already declare readOnly=true, idempotent=true, openWorld=true, and destructive=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the exact fields returned (name, headline, profile URL, public identifier) and the cursor-based pagination model. It stops short of noting rate limits or auth requirements, but it clearly exceeds the annotation baseline.

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?

Three short sentences with zero filler: what it does, what it returns, and how pagination works. The most important information (the resource and its 1st-degree scope) is front-loaded.

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, but the description compensates by listing the returned fields and explaining the cursor-based pagination, so an agent knows what comes back and how to page. Combined with annotations covering the safety profile, this is nearly complete for a simple list tool; only error or empty-result behavior is unspecified.

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 both parameters (limit, cursor) are already fully documented in the schema. The description reinforces the cursor-pagination concept, which is minor added value, but adds no syntax or defaults beyond what the schema states. Baseline 3 is appropriate when the schema does the heavy lifting.

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 and resource ('List your LinkedIn connections') and scopes it precisely to 1st-degree connections, which distinguishes it from sibling tools like linkedin_get_shared_connections and linkedin_list_connection_requests. It does not explicitly name an alternative tool, but the 1st-degree qualifier makes the resource unambiguous.

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 description (retrieve your own connection list), and the sibling set makes the intent fairly clear. However, there is no explicit when-to-use guidance or contrast with alternatives such as linkedin_search_people or linkedin_get_shared_connections, leaving routing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description goes further by disclosing the payload (text, timestamp, sender ID, read status, attachments, sender name/headline/profile link) and, critically, the pagination invariant that a returned page is not necessarily the start of the conversation. That warning is behavioral context not derivable from the schema.

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-loaded with purpose and return contents, then prerequisites, then pagination. Slightly redundant in restating limit's default 50 / max 250 that the schema already carries, but every sentence otherwise earns its place.

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?

No output schema exists, so the description carries the return-value burden and does so thoroughly, including field-level contents and the has_more/next_cursor pagination contract. Nothing an agent needs to call this correctly and iterate pages is missing.

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 schema documents limit and cursor adequately and the baseline is 3. The description adds cross-call meaning to cursor by tying it to next_cursor and has_more across repeated calls, which the schema's per-parameter text does not fully convey.

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 (Get) and resource (messages from a LinkedIn DM conversation) and immediately distinguishes itself from linkedin_list_conversations by naming that tool as the prerequisite for obtaining chat_id. Ordering ('newest first') is front-loaded so the agent knows the shape of the result.

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?

Explicitly routes the agent: 'Use linkedin_list_conversations first to get the chat_id,' and prescribes the exact pagination loop (call again with same chat_id and cursor=next_cursor, repeat until has_more is false). Both the entry condition and the continuation condition are stated, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds behavior the annotations cannot: null for fields LinkedIn does not expose, and that the hiring team is included only 'when LinkedIn shows them'. Useful but not exhaustive about failure modes (e.g. invalid ID or private job).

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?

Three sentences, front-loaded with the core action before the return-field detail. The middle return-value sentence is long but every clause maps to a distinct output field, so little is wasted.

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 carries the full burden of describing returns, and it enumerates them thoroughly (job fields, apply info, hiring team with profile URLs) plus the null-handling rule. Nothing an agent needs to call or interpret this tool is missing.

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 already documents the 'job' parameter with URL and numeric-ID examples. The description restates the same URL-or-ID duality without adding format, validation, or normalization semantics, so baseline 3 applies.

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 and resource ('Get one LinkedIn job posting') and the exact input forms (URL or job ID). The closing pointer to linkedin_search_jobs distinguishes it from the sibling search tool, so an agent can tell get-one from search-many without opening schemas.

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?

Explicitly says where to obtain valid inputs ('Get job URLs from linkedin_search_jobs'), which routes the agent to the alternative for discovery. It does not state when-not to use it, but the get-vs-search context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior beyond that: results are newest-first, cursors are type-specific, and the final page may be empty — all of which affect correct pagination.

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?

Dense but front-loaded: the purpose comes first, then the cross-tool linkage, then pagination notes. Every sentence carries actionable information, though the cross-reference chain makes it longer than strictly minimal.

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 compensates by naming the returned identifiers (postUrl, activityUrn, commentId) and their downstream uses, plus pagination behavior. An agent has everything needed to call it and consume the result 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 coverage is 100%, so the baseline is 3. The description still adds meaning the schema does not carry: cursors must be replayed with the same 'type' because they are type-specific, and commentId has distinct cross-tool semantics depending on whether the item is a comment or a reaction.

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 and resource ('List your own LinkedIn engagement activity') and immediately narrows scope to the two activity types, with 'most recent first' ordering. It is clearly distinguished from siblings like linkedin_get_post_comments and linkedin_get_post_reactions, which concern other people's engagement rather than your own.

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?

Explicitly routes the agent: pass postUrl/activityUrn to linkedin_get_post_comments or linkedin_get_post_reactions, and use commentId as parentCommentId in linkedin_get_nested_comments to list replies. It names both the alternative tools and the exact condition/data that selects them.

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

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive), so the lower bar applies; the description adds real value on top by specifying sort order and the exact fields each item returns. With no output schema present, documenting the return shape and the nextStart-to-start handshake is meaningful behavioral disclosure.

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?

Three sentences, front-loaded with purpose, then return shape, then pagination. Every sentence earns its place with no redundancy or 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 and only two simple parameters, the description covers purpose, sort order, return fields, and paging, and annotations cover safety. The one small gap is end-of-list behavior (what nextStart is on the final page), but otherwise an agent has what it needs to call and page 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 100%, so both parameters are already documented, giving a baseline of 3. The description restates the nextStart-to-start pagination flow but adds no format or constraint detail beyond what the schema says, so it does not exceed baseline.

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?

Names a specific verb and resource ('List the posts that the connected user saved on LinkedIn') and adds scope ('most recent first'), which no sibling tool shares. An agent can distinguish it immediately from linkedin_get_my_engagement, linkedin_get_post_comments, and the other list/get tools without opening a schema.

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 purpose implies the use case (retrieve saved posts) and the pagination sentence gives a concrete follow-up action, but there is no explicit when-to-use/when-not guidance or named alternative. This is acceptable given no sibling covers saved items, but the description leaves usage to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by noting a connected LinkedIn account is required, but it does not disclose pagination behavior or return shape beyond what the cursor schema implies.

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?

Two tight sentences with no waste; the core action is front-loaded, followed immediately by the chaining instruction and the auth prerequisite. Every sentence earns its place.

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 nested-comment fetch with full parameter descriptions and strong annotations, the description covers purpose, chaining, and account requirements well. It does not explain return values or pagination, but with a rich input schema and no output schema the remaining gap is minor.

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 cursor, activityUrn, and parentCommentId thoroughly. The description reinforces the parentCommentId selection condition (replyCount > 0), but this largely duplicates what the schema already says, so it merits the baseline 3 rather than a higher score.

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 (get nested replies under a specific comment) and explicitly differentiates from the sibling linkedin_get_post_comments by framing itself as the follow-up step. An agent can immediately tell what this tool does and when it applies.

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 chaining instructions: call this after linkedin_get_post_comments, pick a comment where replyCount > 0, and pass its commentId. This is exactly when-to-use guidance tied to a named sibling, leaving little to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety behavior is covered. The description adds real value beyond them by disclosing the result shape and volume cap (~50 posts with text, engagement counts, post URL), which matters since there is no output schema. Rate limits or behavior on private/invalid profiles are not mentioned.

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?

Three tight sentences: capability and identifier forms first, return shape second, disambiguation last. No filler and nothing buried.

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 usefully covers what comes back and the rough page size, and the schema covers pagination. Handling of private profiles, invalid identifiers, or rate limits is left unstated, which is the only real gap for a two-parameter read tool.

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% and the schema already documents both the identifier formats and the cursor continuation semantics. The description's enumeration of URL/slug/URN duplicates the schema rather than extending it, so baseline 3 applies.

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 and resource (get a person's recent posts) and enumerates the accepted identifier forms. It also explicitly separates itself from the sibling company-posts tool, so an agent can pick correctly without opening either schema.

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 a concrete use case ('see what a prospect or a candidate posts about') and names the alternative for companies. It does not address the other plausible alternative, linkedin_search_posts, so the routing story is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a meaningful behavioral constraint beyond the annotations: the tool only works on the authenticated user's own posts. It does not mention auth scopes, rate limits, or return shape beyond metric names, so it is not a 5.

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?

Two sentences, both front-loaded and information-dense. The metric list is stated first and the ownership restriction follows, with no filler or redundancy.

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 compensates by enumerating the metrics returned (impressions, reactions, comments, reshares, CTR, engagement rate) and states the critical ownership constraint. Combined with full schema coverage for both parameters and read-only annotations, an agent has everything needed to call it 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 100%, with the 'post' parameter documenting accepted URL/URN formats and 'include_demographics' documented with a default. The description does not add syntax or format details beyond the schema, so the baseline 3 is appropriate when the schema does the heavy lifting.

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 names a specific verb ('Returns'), the resource ('engagement metrics... for one of your own LinkedIn posts'), and enumerates the exact metrics returned. It clearly distinguishes itself from siblings like linkedin_get_post_comments or linkedin_get_post_reactions by being a metrics tool scoped to the caller's own posts.

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 a clear usage context and an explicit exclusion: only posts authored by the connected account, and analytics for other users' posts are unavailable. However, it does not name an alternative tool or suggest what to use when the post is not yours, so it falls short of a full when/when-not/alternatives statement.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds value on top by disclosing the return payload (comment text, commenter profile, timestamp) and warning against constructing an activity URN from a ugcPost/share URL. Pagination beyond the cursor is not mentioned, but the schema's cursor description covers it.

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?

Purpose is front-loaded, followed by inputs, outputs, then the edge-case warning. Four sentences with essentially no filler. The final sentence is dense but earns its place as a real error-prevention note.

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 correctly compensates by enumerating the returned fields and by covering both identifier paths plus the URL caveat. Remaining gaps are minor (no note on result ordering or typical batch sizes), and the cursor field in the schema handles paging.

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, but the description adds genuine semantics beyond the schema: it names the origin of activityUrn (linkedin_get_person_posts) and explains the URL-format exception where the embedded number is not an activity ID. That is meaningful guidance the schema does not provide.

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?

Specific verb+resource ('Get comments on a LinkedIn post') with a clearly named input source, so an agent knows exactly what it retrieves. It does not, however, differentiate itself from the close sibling linkedin_get_nested_comments (replies on comments), which risks misrouting.

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 concrete guidance on when to use each identifier: activityUrn preferred and sourced from linkedin_get_person_posts, postUrl as the fallback. It also flags a specific input trap (URLs containing 'ugcPost'/'share' whose number is not an activity ID), which is real usage guidance, though it never excludes or compares against sibling tools.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds real value beyond them: the connected-LinkedIn-account requirement, the fact it works on your own comments, and the shape of the return (reactor profiles plus reaction types). It stops short of detailing pagination behavior, which the cursor param implies.

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-loaded with the purpose, then two sentences covering parameter sourcing and return content. The parenthetical about own-comments plus account requirement is slightly dense but each clause carries useful information.

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?

No output schema exists, so the description correctly describes the return content (reactor profiles and reaction types). It covers both invocation modes, identifier sources, and the auth prerequisite, leaving nothing essential for a correct call unstated.

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 all four parameters. The description restates which tools supply activityUrn and commentId and adds the 'your own comments' nuance, but adds little syntax or format detail beyond the schema. Baseline 3 is appropriate.

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 and resource ('Get reactions on a LinkedIn post or on a specific comment') and distinguishes the post-level vs comment-level modes. An agent can tell it apart from siblings like linkedin_get_post_comments or linkedin_react_to_post without opening a schema.

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 clear branching logic: pass activityUrn or postUrl for the post, add commentId to switch to comment reactions, and names the sibling tools that produce each identifier. It does not explicitly state when to prefer this over related tools (e.g. linkedin_get_my_engagement), but the conditions are well-covered.

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

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

The annotations already declare read-only, idempotent, open-world, non-destructive behavior, so the bar is lower. The description adds a real behavioral detail beyond them: a second company fetch happens by default, driven by the most recent experience entry with a company URL. It doesn't cover auth or rate-limit characteristics, which keeps it from a 5.

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?

Three sentences, front-loaded with the operation and return surface, then the use case, then the sibling routing. No filler and nothing buried.

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 only two parameters, no output schema, and an annotated read-only profile, the description is complete: it enumerates the returned fields, explains the default side-fetch, and covers retrieval. An agent can call it correctly without further inference.

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 both parameters are already fully documented with examples, and the description adds little beyond restating the identifier forms. The one extra signal is the default-on company lookup, which is also in the schema default.

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 and resource ('Get one person's LinkedIn profile') and enumerates the returned fields (name, headline, positions, education, counts), so it cannot be mistaken for the company or post tools. It also names the two nearest siblings it is not.

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 states a concrete use case ('research a prospect or a candidate, for example before you contact them') and explicitly routes agents elsewhere: linkedin_search_people to find a person first, linkedin_bulk_get_profiles for 2 to 10 profiles. When-to-use and alternatives are both spelled out.

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

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

Annotations already declare the safe read/idempotent profile, but the description adds non-obvious behavior: the Premium prerequisite and its blurred/empty fallback, the pagination mechanic, and the fact that some entries are aggregated with no profile URN. These are real traits an agent cannot infer from structured fields.

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 purpose in the first clause, then adds only high-value caveats (Premium gating, pagination, aggregated entries). Every sentence earns its place with no redundancy.

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 carries the burden of describing return semantics, and it does so well: aggregated entries without profile URNs and the blurred/empty fallback. An agent has everything needed to call and interpret the tool.

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% and the schema already documents `start` and the nextStart handoff, so the baseline is 3. The description reinforces the pagination contract and ties it to the aggregated-entry behavior, adding modest value beyond the schema text.

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 ("Returns the recent viewers of your own LinkedIn profile") and names the exact surface ("Who viewed your profile"). The 'your own profile' scoping cleanly separates it from sibling tools like linkedin_get_profile or linkedin_get_my_engagement.

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 clear context for use: it is the viewer-list surface on the connected account, and notes the Premium gating that determines whether results are usable. It does not, however, name an alternative tool or state when a sibling would be preferred, so it stops short of explicit when-not guidance.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so safety is covered. The description adds genuinely new operational context: a hard pacing limit of 3 calls/minute per account and cursor-based pagination. It doesn't say what an empty result implies (no shared connections vs. an inaccessible profile), which would be the last piece.

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 short sentences, all front-loaded: purpose first, then the accepted identifier forms, then pagination, then pacing. Nothing is redundant with itself and every sentence carries usable information.

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 read-only annotations, a fully documented 2-parameter schema and no output schema, the description covers what to pass, how to page, and how fast you may call it. An agent is still left guessing at the shape of each returned connection, a minor gap given there is no output schema.

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% and both parameters are fully described in the schema, including the URL/slug/URN forms that the description repeats. The description adds no format or resolution details beyond the schema, so the baseline of 3 applies.

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 precise verb and resource — mutual/shared connections between the caller and a target profile — and defines the concept inline ('the people in your 1st-degree network who are also connected to the target'). This clearly separates it from linkedin_get_connections (own network) and linkedin_search_people.

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 concrete intent ('finding who can give a warm introduction') and an explicit batch constraint ('Look up one person at a time'), plus a rate limit of 3 lookups/minute. It does not name a sibling alternative (e.g. linkedin_get_connections) for the case where the caller wants their own list, so it stops short of full when/when-not guidance.

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

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

Annotations already establish readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds meaningful context beyond that: the result set is limited to pages the caller administers, the fields returned, and the caveat that messaging status is only present 'when LinkedIn reports it' — a real data-availability disclosure.

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?

Two sentences, zero filler, and the essential scope ('that you administer') is front-loaded before the returned fields and the follow-on hint. Every clause earns its place.

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 compensates by enumerating the returned fields and flagging the conditional messaging value, which is what an agent needs to consume the result. Minor remaining gap: nothing about result limits or whether the list can be empty if the user administers no pages.

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?

The tool takes zero parameters, which is the baseline-4 case. The description correctly notes that page_id values obtained here are the inputs other tools expect via as_page, tying the empty schema to the wider workflow.

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 (list) and resource (LinkedIn company pages) with a scoping qualifier (that you administer), and enumerates the returned fields (page_id, name, URL, messaging flag). This cleanly distinguishes it from sibling reads like linkedin_get_company and linkedin_bulk_get_companies.

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 second sentence gives downstream usage guidance — pass page_id as as_page to publish, schedule, comment or react as a page — which is useful but is about what to do after calling, not when to call this rather than another listing tool. No explicit when-not or alternative selection criteria are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the safety profile is covered. The description adds 'pending'-only scoping and cursor-based pagination, but the pagination point largely overlaps the cursor parameter already documented in the schema.

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?

Three short sentences, front-loaded with the core purpose and no filler. The direction sentence duplicates schema information slightly, keeping it from a perfect score.

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, zero-required-parameter list tool with 100% schema coverage and full annotations, the description covers purpose, direction semantics, and pagination behavior. A description of return values is the only absent element, and that is minor for a paginated list whose shape is implied.

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 all three parameters are already fully documented, including the direction enum and its default. The description restates the direction semantics without adding format, constraints, or edge-case detail beyond the schema, which is the expected baseline.

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 with a clear scope qualifier: 'List pending LinkedIn connection requests'. The word 'pending' implicitly separates it from linkedin_get_connections (accepted connections) and linkedin_manage_connection_request (accept/reject), but no sibling is named explicitly, so it stops short of a 5.

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 explains how to use the direction parameter ('sent' vs 'received'), which is real usage context, but gives no explicit when-to-use-this-vs-alternatives guidance against linkedin_get_connections or linkedin_manage_connection_request. Usage is implied rather than stated.

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

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

Beyond the readOnly/idempotent annotations it discloses two non-obvious traits: a daily limit on inbox reads that each page consumes, and that participant search only scans recent conversations, requiring cursor to continue scanning. It also notes last-message text is truncated to 300 characters and that fields appear only 'when LinkedIn provides' them. It stops short of describing rate-limit numbers or failure modes, but the behavioral coverage is well above the annotation baseline.

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-loaded with purpose, then use cases, then return shape, then pagination and pacing – a sensible order. It runs long at eight sentences and a couple of clauses are justificatory filler ('so no profile lookup is needed', 'so you can sort the inbox'), but nothing is genuinely off-topic.

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?

Covers everything an agent needs for a 7-parameter, zero-required read tool with no output schema: what comes back per conversation, how paging terminates, how polling works, the quota cost, and the scan limit on participant search. No material gap remains.

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?

With 100% schema coverage the baseline is 3, but the description adds cross-parameter meaning the schema only states individually: switching inbox to sales_navigator, carrying the same inbox value alongside cursor, combining participant with unread_only/after/before, and using after as the polling anchor. These combinations are the practically hard part of calling this tool correctly.

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 and resource (list the user's LinkedIn message conversations / inbox) and enumerates the concrete questions it answers (unread messages, who replied, replies from a company, one person's thread). It also distinguishes itself from reading messages by promising last-message text and participant headline so 'no profile lookup is needed' and the inbox can be sorted 'without opening each conversation.'

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-to-use triggers tied to user phrasing, names the recipe for company/period reply hunting (list with after, optionally unread_only, then read headline and last message), and covers pagination continuation with the same arguments plus next_cursor. It even prescribes the polling pattern: pass after with the time of your last check, which usually reads one page.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the mutation and irreversibility profile is covered structurally. The description's main addition - the shared_secret requirement per action - is essentially duplicated in the schema, and it adds nothing about error behavior or reversibility beyond the annotations.

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?

Two tight sentences, front-loaded with the source-of-truth list tool, then split cleanly by direction. Every clause earns its place with no redundancy or 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 3-parameter mutation tool with a full schema and safety annotations, the description supplies the workflow context (list first, then act by direction) an agent needs. It omits success/failure semantics and reversibility, but those are largely implied by the destructiveHint annotation and no output schema is expected.

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 connection_request_id, action, and shared_secret, including the enum values and the shared_secret requirement per action. The description restates the same shared_secret/direction logic without adding syntax or format detail, so the baseline 3 applies.

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 set (accept, decline, withdraw) against a specific resource (a LinkedIn connection request) and anchors the resource's origin to linkedin_list_connection_requests. An agent can distinguish this management tool from the sibling list tool and the send tool without opening any schema.

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 clearly states where the input comes from (linkedin_list_connection_requests) and which action applies to each direction, effectively routing received vs sent cases. It stops short of naming an explicit alternative or exclusion (e.g. use linkedin_send_connection_request to create one), so it is strong context rather than full when/when-not guidance.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds the observable side effect (clearing the unread badge) and clarifies that a sibling read operation won't produce it, though it says nothing about permissions or failure modes.

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?

Three short sentences, front-loaded with the action and effect, followed by the disambiguation and the sourcing hint. 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 single-parameter write tool whose annotations already cover idempotency and destructiveness, the description supplies the action, effect, sibling distinction, and ID provenance. Nothing needed to invoke it correctly is missing.

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 chat_id is already documented, making the baseline 3. The description adds provenance value by telling the agent to use linkedin_list_conversations to get the chat_id, which is beyond what the schema states.

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 and resource ('Mark a LinkedIn conversation as read') plus the concrete effect ('clearing its unread badge'), and distinguishes itself from linkedin_get_conversation_messages by noting that reading does not clear the badge.

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?

Explicitly routes the agent: use this to clear the unread state, and it names the sibling that does NOT achieve this ('Reading messages via linkedin_get_conversation_messages does not clear it'), plus tells the agent how to obtain the chat_id.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is carried structurally. The description adds the acting-identity distinction (yourself vs a page you administer), which is real context, but says nothing about whether an existing reaction is replaced or how to undo one — a meaningful gap given idempotentHint=false and destructiveHint=true.

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?

A single front-loaded sentence that leads with the verb and resource; nothing is padded. The parenthetical reaction list duplicates the schema enum and is the one element that does not earn its place.

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 0 required parameters, full schema coverage and annotations supplying the safety profile, the description covers the essentials for a small write tool. It still omits the 'at least one of post_id or post_url is required' constraint and the replace-vs-add behavior of an existing reaction, which are the main things an agent could get wrong.

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 every parameter is documented in the schema, including the post_id/post_url alternative and the as_page flow. The description only restates the reaction enum and the self/page option, adding no semantics the schema does not already carry, so the baseline of 3 applies.

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 (React) and resource (a LinkedIn post or a comment on it), and enumerates the reaction types, so the operation is unmistakable. It implicitly differentiates from siblings like linkedin_comment_on_post and the read-only linkedin_get_post_reactions, but never names them or states the contrast explicitly.

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?

There is no when-to-use guidance, no statement of when to prefer this over linkedin_comment_on_post, and no prerequisites called out. The only routing hint (that as_page requires a page_id from linkedin_list_company_pages) lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, but the description adds genuinely new behavior: a hard pacing limit of 3 searches per minute shared across people, Sales Navigator and job searches, plus the consequence that parallel calls queue or are refused with a wait time. It also discloses the returned fields and pagination-cursor behavior, which no annotation covers.

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 core purpose and the routing hints are front-loaded, and the pacing warning is placed as a clearly delineated final paragraph. A few sentences are lower value, notably "Useful for sourcing open roles or tracking hiring activity in a market," which restates the obvious for a search tool.

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 10 optional parameters, no output schema and no required fields, the description covers everything an agent needs: what to pass, how filters interact with the keyword field, what comes back, how to paginate, and the throttling constraints that can cause failures. Nothing material for correct invocation is left unstated.

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, and the description earns an extra point by adding meaning the schema lacks: that a location string is auto-resolved to a LinkedIn region, and that the cursor must be reused with identical filters to continue the same search. It does not explain the interaction between sort_by and the other filters, which keeps it below 5.

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?

"Search open LinkedIn job postings by keywords and/or a region" is a specific verb plus resource, and 'job postings' cleanly separates it from linkedin_search_people, linkedin_search_posts and the single-record linkedin_get_job. The added example ("Stripe account executive") makes the scope concrete rather than tautological.

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 states when to use this tool versus workarounds explicitly: to see one company's roles, put the company name in keywords; to find remote jobs, use work_type ["remote"] rather than the word 'remote'. It also names the shared rate budget with people and Sales Navigator searches and instructs sequential calling, so the agent knows both the correct and incorrect invocation patterns.

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

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

Annotations already cover the read-only, idempotent, open-world safety profile, but the description adds material behavior the annotations cannot convey: a hard pacing limit of 3 searches/minute shared across people, Sales Navigator and job searches, the instruction to send searches serially, and the consequence that parallel calls queue or are refused with a wait time. It also explains that text filters are resolved to LinkedIn IDs and that total_count may be null.

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-loaded with purpose and routing, then parameters, then return values, then pacing — a logical order with no filler sentences. It is dense and fairly long, but nearly every clause carries operational value; the packing example and pacing paragraph are the only candidates for trimming.

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 an 8-parameter, zero-required, no-output-schema search tool, the description covers invocation strategy, return fields, pagination via cursor, null-total semantics, and account-safety constraints. An agent has everything needed to call it correctly and safely without further context.

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, but the description adds real semantics beyond the schema: example keyword packing ("Head of Procurement Bosch"), that a raw people-search URL can be passed instead of filters, that text filters are auto-resolved to IDs, and how connection_of combines with network_distance and optional keywords. It does not cover industry or profile_language, hence not a 5.

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 (LinkedIn people search) and immediately scopes it: the user's own account, no Sales Navigator needed. It distinguishes itself from linkedin_get_profile and linkedin_search_sales_navigator by name, so an agent can route correctly without opening any schema.

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?

Explicit when-to-use cases are given (prospects, candidates, contacts by title/company/skill/location, who holds a role at a company), plus explicit alternatives: linkedin_get_profile for full profiles and linkedin_search_sales_navigator for seniority/function/years-of-experience filters. This is genuine when-and-when-not guidance.

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

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

The annotations already mark this as a read-only, idempotent, open-world operation, so the description's job is to add behavior on top. It does so: a 10-post per-call cap, the exact returned fields, the caveat that LinkedIn returns loosely related posts, and how keywordsInText is computed. That is material behavior an agent could not infer from the structured fields.

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 purpose, then filters, then return shape, then follow-up routing. Nearly every sentence earns its place, though the return-value enumeration is dense enough that an agent must read to the end to find the useful pagination note.

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?

No output schema exists, so the description must describe results, and it does: per-post fields, the 10-post limit, and the caveat about loosely related matches. Pagination, filtering, and downstream tool routing are all covered, so nothing needed to call it correctly is missing.

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 schema already documents all four parameters. The description still adds matching semantics, namely that keywordsInText is true only when the post text contains every keyword (or one of several joined with OR) and how exact phrases work, which meaningfully shapes how the agent writes queries.

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?

A specific verb plus resource ('Search LinkedIn posts by keywords') is followed by three concrete use cases (finding people asking for a service, hiring announcements, topical posts). That is enough to separate it from siblings like linkedin_search_people, linkedin_search_jobs, and linkedin_get_company_posts without opening any schema.

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 gives clear usage context, routes the agent to linkedin_get_post_reactions and linkedin_get_post_comments for follow-up detail, and explains when to pass nextCursor. It stops short of an explicit 'do not use this for X' exclusion, such as distinguishing it from search_people or company posts.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the bar is lower, yet the description still adds substantial operational context: a hard pacing limit of 3 searches/minute shared across people, Sales Nav and job searches, a requirement to send searches serially, and the consequence for parallel calls. It also discloses the subscription prerequisite and that results include open-profile, premium, and tenure data.

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-loaded with purpose and the sibling comparison, then the exclusion, then operational constraints. It is longer than most definitions, but the pacing sentences carry real operational value rather than filler; minor tightening of the "richer results" sentence would make it a 5.

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 10-parameter, zero-required search tool with no output schema, the description covers the missing pieces an agent needs: result shape (one page of leads), pagination via cursor, mutual exclusivity of URL versus filters, ID resolution, and the account-safety pacing regime. Nothing essential to a correct call is left to inference.

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 each of the 10 parameters is already documented in the schema; the description adds little parameter-specific meaning beyond restating that text values such as "San Francisco" are auto-resolved to LinkedIn IDs and that one call returns one page with cursor paging. Baseline 3 is appropriate when the schema carries the parameter detail.

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 and resource ("Search LinkedIn Sales Navigator for people (leads)") and explicitly names the differentiator versus the sibling classic search (seniority, function, years of experience filters). An agent can route between linkedin_search_people and this tool without opening either schema.

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-to-use triggers (user asks for a Sales Navigator search or lead list, or needs Sales-Nav-only filters), an explicit fallback ("without a subscription, use linkedin_search_people"), and an explicit when-not ("does not create or change saved lead lists"). Alternatives are named, not implied.

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

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

Annotations already declare readOnly=false, destructive=true, openWorld=true, and idempotent=false, so the write/irreversibility profile is covered. The description adds useful detail on accepted identifier formats and the 300-character message cap, but says nothing about rate limits, duplicate/pending-request behavior, or auth needs that annotations don't already imply.

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?

Three tight sentences, front-loaded with the core action and with no filler. It is appropriately sized, though the identifier-format sentence slightly duplicates the schema.

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 and a mutation tool, the description does not state what the agent should expect on success or failure (e.g., pending vs. failed request), nor how it relates to manage/list connection request siblings. It is adequate for invocation but leaves behavioral gaps for a destructive, non-idempotent action.

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 both parameters are fully documented in the schema, including identifier formats and the 300-character limit. The description largely restates this, adding no syntax or format meaning beyond what the schema already provides, so the baseline 3 applies.

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 ('Send a LinkedIn connection request to a person'), which is unambiguous. However, it does not differentiate itself from the sibling linkedin_manage_connection_request, which likely also touches connection requests, so an agent must infer the split.

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?

No when-to-use guidance is given. There is no mention of when to prefer this over linkedin_manage_connection_request (e.g., for accepting or withdrawing), nor any prerequisite such as being logged in or not already being connected. Usage is only implied by the verb 'send'.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: InMail eligibility for non-connections, the automatic subject derivation (first words of the message, up to 60 characters) when subject is omitted, and that a new conversation returns a chat_id for later replies. It does not mention irreversibility of a sent message or any rate limiting, which keeps it from a 5.

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 definition is front-loaded with purpose and mode selection, then moves to the Sales Navigator edge case and the return value. Nearly every sentence carries information, though the subject-derivation rule is stated twice (description and schema), which is mild waste.

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 six-parameter mutation tool with no output schema, the description covers both call paths, the InMail/Sales Navigator special case, and the returned chat_id. What remains unaddressed is failure behavior — what happens when InMail is unavailable or the recipient cannot be resolved — which would help an agent recover from errors.

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, but the description adds meaning on top: it enumerates the accepted forms of recipient_identifier (profile URL, public ID, URN), ties chat_id to its source tool, and scopes subject to Sales Navigator InMail only while explaining the fallback. The duplication of the subject fallback with the schema text is the only redundancy.

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 first sentence gives a specific verb and resource (send a LinkedIn message) scoped to the user's own account. It then explicitly separates the two operating modes — new message to a person vs. reply in an existing chat — and names the sibling tool (linkedin_list_conversations) that supplies the chat_id. An agent can distinguish this from linkedin_send_connection_request or linkedin_comment_on_post without opening the schema.

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 clearly routes between the two modes: pass recipient_identifier to write to a person, pass chat_id to reply, and the schema confirms they are mutually exclusive. It also flags InMail as the path for people who are not connections. It stops short of naming alternatives for the non-connected case (e.g. sending a connection request first) or stating when not to send at all.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral value by disclosing the return contents, especially the premium-feature flags (Sales Navigator, Recruiter), which determine which other tools will work — useful context beyond the annotations.

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?

Two sentences, front-loaded with the return payload and ending with actionable guidance. No filler; every clause earns its place.

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 present, the description correctly carries the return-value burden and enumerates the key fields. It is complete for a no-parameter identity/capability probe, though it could note whether the premium flags can be empty when no subscription is active.

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?

The tool takes zero parameters, so the baseline is 4. There is nothing parameter-related to clarify.

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 ('Returns') plus the resource (information about the connected LinkedIn account) and enumerates exactly what is returned: display name, profile URL, URN, and active premium features. This is unmistakably distinct from every sibling, none of which report account identity.

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?

Provides clear when-to-use guidance ('Use this to understand which LinkedIn capabilities are available before choosing search or messaging strategies'), which routes the agent correctly relative to the search/messaging siblings. It stops short of naming specific alternative tools, so it is clear context rather than explicit alternatives.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the write/submit nature is conveyed structurally. The description adds the destination ("LinkMCP team") and a user-consent guardrail, but it does not explain the odd destructiveHint for what is a submission tool, whether submission is reversible, or what confirmation the caller receives. With annotations covering the safety profile, this modest added context merits a 3.

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?

Two tight sentences with zero redundancy, purpose first and the usage restriction second. Every clause earns its place.

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 three-parameter submission tool with no output schema and full schema coverage, the description supplies purpose and the when-to-use guardrail that the structured fields cannot. It stops short of describing post-submission behavior (confirmation or acknowledgement), a minor gap rather than a blocking one.

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 type/message/context are fully documented in the schema, including per-enum meanings and nested context fields. The description only echoes the enum values already listed in the schema, adding no syntax, format, or sizing guidance beyond it. Baseline 3 applies when the schema does the heavy lifting.

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?

Specific verb+resource+destination: "Send the user's feedback, feature request, bug report or help request to the LinkMCP team." This is unmistakably distinct from every sibling, which are all LinkedIn data/action tools. An agent can identify the operation without opening the schema.

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?

"Use it only when the user asks to send feedback or to contact LinkMCP support" gives an explicit trigger and an implicit exclusion (do not use proactively). It does not name alternatives, but no sibling is a plausible substitute for this tool, so the omission is harmless.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real value beyond them by disclosing the result taxonomy (valid/invalid/catch-all/unknown) and that MX provider details are returned, which tells the agent what to expect from the external lookup.

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?

Two compact sentences, front-loaded with the validation purpose and followed by the return values; nothing is redundant or padded.

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 carries the return-value burden and does so adequately by naming the four result states and MX details. It stops short of explaining what 'catch-all' or 'unknown' mean or any timeout/rate behavior of the external lookup, 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?

Only one parameter and schema description coverage is 100%, so the schema fully documents the address and its example. The description adds no format or syntax detail beyond that, which is the expected baseline.

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 and resource ('Check whether an email address can receive mail') and enumerates the possible outcomes, so an agent can tell it apart from discovery siblings like find_email without opening the schema.

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 purpose makes the use case implicit (verify deliverability before sending or storing an address), but there is no explicit when-to-use guidance, no mention of when not to use it, and no named alternative such as find_email.

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