LinkMCP: hosted LinkedIn MCP server

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 genuine behavioral context beyond that: that company_domain yields "significantly more reliable results" than company_name, which informs accuracy expectations. No auth or rate-limit detail, but the added reliability hint earns above-baseline credit.

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 the core purpose front-loaded and zero filler; the prerequisite and accuracy guidance follow logically. 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 simple read-only lookup with no output schema, the description conveys what is returned (work email) and the inputs needed. It is essentially complete, though it could note behavior when no email is found, a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters including that company_domain is "Recommended for best accuracy." The description's domain-vs-name reliability note largely echoes the schema, so it meets the baseline without adding new syntax or format 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 ("Find") and resource ("a person's work email address") with the required inputs (name and company), making it immediately distinguishable from siblings like validate_email and find_mobile. An agent can tell exactly what this returns 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?

Explicitly routes the agent: if name/company is missing, use linkedin_get_profile first, and it recommends company_domain over company_name for reliability. There is no explicit when-not-to-use guidance (e.g., vs validate_email), but the prerequisite and preference guidance 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=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 the safe, idempotent, open-world read profile, so the bar is lower. The description adds genuine behavioral value beyond that: a name input returns a single company on a clear match, otherwise a candidate list to choose from—an output-shape behavior an agent needs and the annotations do not convey.

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, front-loaded with the core action and then the two parameter branches. No padding, and the caveat about slug guessing is placed exactly where the agent would otherwise err.

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 some return-value burden and does partially address it via the name-match/candidate-list behavior. It does not describe what a profile object contains, but that is a minor omission for a lookup tool with fully documented parameters.

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 the schema lacks: LinkedIn slugs often differ from the company name, so a name lookup should not be replaced by a guessed slug. That rationale directly shapes parameter choice.

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 LinkedIn company profile.' It is clearly distinguishable from the bulk sibling linkedin_bulk_get_companies and from linkedin_get_company_posts by scope, though it never names an alternative explicitly, which keeps it 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?

Gives real conditional guidance: use identifier when known, use name when only the name is known, and explicitly warns against guessing a slug. It stops short of when-not-to-use-this-tool guidance (e.g., vs. search or bulk retrieval).

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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the return shape (~50 posts with text, engagement, URL), which matters since there is no output schema, but it says nothing about auth requirements, rate limits, or pagination behavior beyond the schema's cursor.

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 tightly written sentences: the action and accepted inputs come first, the return shape second. No filler and nothing that could be cut.

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 lookup with no output schema, the description covers the input forms and the essential return contents, and annotations carry the safety profile. Pagination semantics are only implied by the cursor parameter, leaving a small gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already well documented. The description repeats the identifier forms (URL, public ID, URN) without adding format or constraint detail beyond the schema, so the 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 a person's recent LinkedIn posts') and the accepted identifier forms, which implicitly distinguishes it from the company-posts sibling. It stops short of naming that sibling or otherwise routing the agent, but the purpose is 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?

No when-to-use, prerequisite, or alternative guidance is given. Nothing tells the agent how this differs from linkedin_get_profile or linkedin_get_company_posts, or when this tool is the right choice over general profile retrieval.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that—no auth requirements, no rate-limit notes, no indication of what a missing/invalid identifier yields.

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 sentence with zero filler, front-loaded with the action and resource. Nothing is wasted or 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?

For a simple read-only getter with full annotation coverage, a 100%-documented schema, and no output schema to explain, the description is minimally adequate. It still omits sibling routing and any notion of what happens on a failed lookup.

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 both parameters thoroughly, including the URL/slug/URN forms and the company-details flag. The description merely restates the identifier formats already present in the schema, adding no new meaning.

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 ("LinkedIn person profile"), and the identifier forms it accepts. The word "person" distinguishes it from linkedin_get_company, but it does not explicitly route against the closest sibling, linkedin_bulk_get_profiles.

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, no exclusions, and no mention of alternatives such as linkedin_bulk_get_profiles for multiple profiles or linkedin_search_people when the URL is unknown. The context is only implied by the tool name.

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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: it clarifies the result set is a mutual-connection intersection and states results are paginated via cursor, which tells the agent to expect multi-page reads.

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 and scope, followed by use case and pagination note. Each sentence carries information and none is padding.

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, read-only, no-output-schema tool, the description covers scope, accepted identifier forms, and pagination — enough to invoke correctly. It could still note behavior when no mutual connections exist or when the target is unreachable, which leaves a small gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both the identifier formats and the cursor semantics are already fully documented in the schema. The description's mention of URL/public ID/URN duplicates that content without adding syntax or constraint detail, 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?

The description states a specific verb and resource ("List the mutual (shared) connections") and immediately scopes it as being between you and a target profile, which is exactly what separates it from the sibling linkedin_get_connections. The parenthetical definition of shared connections removes any ambiguity about the returned set.

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 concrete reason to reach for this tool ("finding who can give a warm introduction"), which is real usage context. It stops short of naming alternatives or exclusions — e.g. that linkedin_get_connections returns your full network, or that target-network-only data comes from a different sibling — so an agent must infer the boundary.

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?

Annotations already cover read-only/idempotent/openWorld, so the description's value-add is disclosure of return fields, page-loop semantics, and the important caveat that participant search 'scans only your most recent conversations.' That scanning limitation is genuine behavioral context not derivable 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?

The first sentence front-loads purpose and the pagination rule comes last, which is the right ordering. The enumerated return fields are slightly verbose but justified because no output schema exists.

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?

Given no output schema, the description compensates by naming the returned fields and explaining the paging loop end-to-end, so an agent can correctly call it repeatedly and interpret results without further documentation.

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 restates the participant behavior and the has_more/next_cursor contract but adds no format or syntax detail beyond what the schema already documents for each 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?

States a specific verb and resource ('List your LinkedIn DM conversations (inbox)') and immediately scopes it against the message-level sibling by noting the return fields are conversation summaries, not messages. An agent can distinguish it from linkedin_get_conversation_messages 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?

Gives clear operational guidance: use the participant identifier to find a specific person's thread, and loop with cursor when has_more is true. It does not name the alternative message-retrieval tool explicitly, so routing to a sibling 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?

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 readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered; the description goes further by disclosing region auto-resolution, cursor continuation semantics ("same search, with the same filters"), and the returned field set despite there being no output schema. That is exactly the added behavioral context this dimension rewards.

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 core action, then filters, then the gotcha, then return shape and pagination. Five sentences is on the long side and the return-field enumeration and "useful for" sentence are somewhat expendable, but nothing is wasted or redundant.

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, all-optional search tool with no output schema, the description covers filters, region resolution, pagination, and output fields — enough to call it correctly. It omits result caps/rate limits and never explains sort_by or the behavior when both keywords and location are omitted, which keeps it from a 5.

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 baseline is 3, but the description adds a genuinely non-obvious semantic: that the word "remote" in keywords does not filter and work_type must be used instead. It also restates location auto-resolution and pagination intent, but leaves sort_by and the default-ordering behavior unaddressed in prose.

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 ("Search open LinkedIn job postings") with scope, filter inventory, and return fields named outright. It is clearly distinguishable from siblings like linkedin_get_job (single posting), linkedin_search_people, and linkedin_search_sales_navigator that share the 'search' or 'job' surface.

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 usage rule ("To find remote jobs, use work_type [\"remote\"], not the word \"remote\" in the keywords") and a rationale ("sourcing open roles or tracking hiring activity"). It never names an alternative tool or a when-not-to-use condition, so it stops short of a 5.

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, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the exact result fields returned, the auto-resolution of text filter values to LinkedIn IDs, and the null-when-unreported semantics of total_count.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with purpose, then returns, then filter resolution, then pagination. Each sentence carries information, though the filter-resolution sentence partially duplicates the schema descriptions. No filler or marketing language.

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 takes on the burden of describing the returned fields and the pagination/nullability behavior, and it covers both invocation modes. The remaining gap is the missing boundary against closely related siblings such as linkedin_search_sales_navigator and linkedin_get_profile.

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 every parameter is already documented in the schema (including the url/keywords mutual exclusivity and the ID-resolution note). The description mostly restates that, adding only the cross-cutting point that text filter values are resolved automatically. Baseline 3 is appropriate when the schema carries the parameter burden.

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 for people') and immediately names the two input modes (keywords/filters vs. a LinkedIn search URL). This separates it cleanly from linkedin_get_profile, linkedin_get_connections, and the other search siblings.

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 tells the agent both ways to drive the tool and points to cursor for follow-up pages, which is real usage guidance. It stops short of naming alternatives or exclusions, e.g. when to prefer linkedin_search_sales_navigator over this tool, so the agent must infer the boundary.

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, so the safety profile is covered. The description adds genuinely new context: a subscription/auth prerequisite on the connected account, and the automatic resolution of text filter values (e.g. 'San Francisco') to LinkedIn IDs. It does not discuss pagination or rate limits, but that is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with the primary action and result benefit, followed by the prerequisite and the auto-resolution note. Each sentence carries information, though the return-field enumeration ('and more') is slightly 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?

For a 10-parameter, no-required-param search tool with no output schema, the description covers the two invocation modes, the auth prerequisite, and a sketch of the richer return payload. Pagination via cursor is left entirely to the schema, which is acceptable given the rich parameter descriptions.

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 every parameter is already documented, including the numeric seniority and network_distance encodings and the Sales-Navigator-only markers. The description's mention of URL mode and automatic ID resolution largely restates what the schema descriptions already say, so the 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 ('Search LinkedIn Sales Navigator for people') and explicitly differentiates from the sibling classic search by promising 'richer results than classic search' with named extra fields. An agent can tell it apart from linkedin_search_people 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 context: two supported modes (keywords+filters, or a Sales Navigator URL), the mutual exclusion of url vs keywords/filters, and the prerequisite of a Sales Navigator subscription. It stops short of an explicit routing rule such as 'use linkedin_search_people when the account has no Sales Navigator seat', so it is clear but not fully 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 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, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real behavioral value the annotations lack: new conversations return a chat_id for later replies, and InMail is available for non-connections. It doesn't warn about irreversibility or send-permission requirements, keeping it below 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 tight sentences; the core action is front-loaded, followed by the two modes and the return-value note. No filler sentences.

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, and the description compensates by stating that a new conversation returns its chat_id. Combined with full schema coverage and annotations, an agent has enough to call it correctly; it could still note failure conditions (e.g. InMail limits or non-connection 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 description coverage is 100%, so the schema already documents all five parameters including mutual exclusivity and the inmail/linkedin_api constraints. The description's parameter references mostly restate that, adding little beyond the 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 ('Send a LinkedIn message') and immediately splits the two supported modes: replying via chat_id vs starting a new conversation via recipient_identifier. This differentiates it from siblings like linkedin_send_connection_request and linkedin_comment_on_post.

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?

Explains which parameter path to use for each scenario and notes InMail applies only to non-connections, giving clear context for selection. It does not name alternative tools (e.g. when to prefer a connection request over an InMail), so it stops short of explicit alternatives/exclusions.

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.