PerfectPost is a LinkedIn content management platform. This MCP server gives AI assistants read and write access to a user's PerfectPost account: published posts with their engagement analytics, drafts lifecycle (create / edit / schedule), and LinkedIn profile data.
Scored across 16 tools
Drafts and posts are cleanly separated (create/get/list/update_draft vs get/list/search/update_post), and read-only metrics tools (get_post_commenters, get_post_likers, get_posts_stats_summary) each target a distinct data type. The two media tools are distinguished by source (base64 attachment vs public URL) with explicit guidance on when to use each. No two tools appear to do the same thing.
Every tool follows a consistent snake_case verb_noun pattern (create_draft, get_post, list_posts, update_draft, search_posts, schedule_draft). Compound names like get_posts_stats_summary and set_draft_media_from_base64 are longer but still predictable and read cleanly.
16 tools is slightly above the ideal range but each covers a distinct slice of the domain: draft lifecycle, media attachment, published-post reading/analytics, and account/org context. Nothing feels redundant or padding, though a couple of read tools could arguably be consolidated.
Draft lifecycle (create, get, list, update, schedule, media) and post reading/analytics/search cover the core workflows well. The main gap is the absence of a delete_draft (or delete/cancel operation), which an agent would likely need to manage drafts fully.
Creates a new LinkedIn post draft for the personal profile or, with organization, for a company page. The content is HTML: use for paragraphs and for line breaks. Works on the personal profile by default; pass organization to target a company page (see list_organizations).
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional draft title | |
| content | Yes | Draft content in HTML | |
| objective | No | Marketing objective: tofu (awareness), mofu (consideration), bofu (conversion) | |
| categories | No | Categories or tags associated with the draft | |
| organization | No | LinkedIn company page to act on instead of the personal profile. Pass the page id or urn returned by list_organizations, or the exact page name. Omit to target the personal profile. | |
| programmingDate | No | ISO 8601 scheduling date (requires the 'publish' scope; otherwise use schedule_draft with a publish token). | |
| scheduledComments | No | Comments to post automatically under the publication, each with its own delay | |
| scheduledReshares | No | Reshares of the post to schedule, each with its own delay |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the create-but-non-destructive profile is already known. The description adds real behavioral value by specifying that content must be HTML and which tags to use (<p>, <br>), which is a formatting requirement an agent would otherwise have to guess. It stops short of covering auth/scope needs or the publish flow.
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, followed by format then targeting. Slight redundancy: the personal-profile default and `organization` routing is stated twice, once implicitly in sentence one and again in sentence three.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter creation tool with full schema coverage and no output schema, the description covers the core invocation story (what is created, where, content format) adequately. It does not mention what is returned (e.g., a draft id needed for set_draft_media_* or schedule_draft) or the publish-scope interaction with programmingDate, though the latter is covered in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's `organization` explanation (default profile, company page target) largely restates what the schema already says for that property, and the HTML note overlaps the `content` property description, so added meaning beyond structured fields is modest.
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 ('Creates a new LinkedIn post draft') and immediately scopes the two targets: personal profile vs. company page via `organization`. An agent can distinguish this from update_draft, schedule_draft, and list_drafts 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?
Explicitly states the default behavior (personal profile) and the condition that switches targets (pass `organization`) and points to list_organizations for valid values. It does not, however, say when to prefer this over update_draft for an existing draft or how it relates to schedule_draft.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the full content of a LinkedIn post draft, including whether it targets the personal profile or a company page.
| Name | Required | Description | Default |
|---|---|---|---|
| draftId | Yes | The draft identifier |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful return-content context (profile vs company page targeting) but omits behavior on missing/invalid drafts or any format details, so it only modestly 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?
A single, front-loaded sentence with the primary action first and the return-content clause second; 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?
For a simple one-parameter read tool with safety annotations and no output schema, the description covers purpose and return content adequately. It would be marginally stronger with a note on missing-draft behavior, but nothing essential is missing for correct invocation.
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 a single required draftId parameter, so the schema fully documents the input. The description adds no further parameter semantics, which is the expected baseline 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 (retrieves a LinkedIn post draft) and adds scope detail about what the content includes (profile vs company page target). It is readily distinguishable from siblings like list_drafts or get_post, but it does not explicitly name those siblings to reinforce the distinction.
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 use this tool versus alternatives such as list_drafts (for enumeration) or update_draft, nor any prerequisite or eligibility conditions. Usage must be inferred entirely from the purpose sentence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the connected user's full LinkedIn profile: identity, headline, summary, posting statistics, preferences, and the number of company pages they administer (use list_organizations for details).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered structurally. The description adds meaningful behavioral context beyond that by disclosing the breadth of the payload — identity, posting statistics, preferences, and a company-page count — which tells the agent roughly how heavy the response is and what it can extract from one call.
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 the core action and payload front-loaded, and the sibling routing hint placed at the end where it does no harm. Every clause earns its place by naming a returned field or a routing rule.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must carry the burden of describing the return value, and it does so by enumerating the profile sections returned. Combined with annotations that establish it as a safe read, an agent has everything needed to call it correctly and interpret the result.
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 there is nothing for the description to disambiguate and the baseline is 4. No parameter semantics are needed or missing.
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 ('Retrieves') plus resource ('the connected user's full LinkedIn profile'), followed by an enumeration of the exact fields returned (identity, headline, summary, posting statistics, preferences, company page count). It also names the sibling tool to use for details on one of those fields, so an agent can distinguish it from list_organizations 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?
The parenthetical '(use list_organizations for details)' gives an explicit routing rule away from this tool for company-page data. However, it provides no when-not guidance for the profile read itself (e.g. whether it requires an authenticated connection, or whether it should be called once per session), 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.
Retrieves the full details of a LinkedIn post, including its text, metrics and simplified media. Works on the personal profile by default; pass organization to target a company page (see list_organizations). For a company page, the post urn must belong to that page.
| Name | Required | Description | Default |
|---|---|---|---|
| urn | Yes | LinkedIn URN of the post | |
| organization | No | LinkedIn company page to act on instead of the personal profile. Pass the page id or urn returned by list_organizations, or the exact page name. Omit to target the personal profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior the annotations do not: the personal-profile default, and the precondition that a page-scoped urn must belong to that page.
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 purpose, then default behavior, then the page constraint. Every sentence carries information and nothing is repeated from the annotations.
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 still says what is returned (text, metrics, simplified media) and covers both targeting modes plus the urn/page relationship. An agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, and the organization parameter is already documented as optional in the schema. The description rises above baseline by stating a cross-parameter constraint (a company-page urn must belong to the targeted page) that the schema does not express.
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 ("Retrieves the full details of a LinkedIn post") and enumerates the payload (text, metrics, simplified media), which is enough to separate it from siblings like get_post_likers, get_post_commenters and get_posts_stats_summary 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?
Explains the default target (personal profile) and the condition that switches to a company page, pointing at list_organizations as the source of the organization value. It gives clear usage context but offers no explicit when-not-to-use or alternative sibling to call instead for a lighter read.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the comments and their authors for a published LinkedIn post, with pagination. Works on the personal profile by default; pass organization to target a company page (see list_organizations). For a company page, the post urn must belong to that page.
| Name | Required | Description | Default |
|---|---|---|---|
| urn | Yes | LinkedIn URN of the post | |
| limit | No | Number of comments to return | |
| offset | No | Number of comments to skip | |
| organization | No | LinkedIn company page to act on instead of the personal profile. Pass the page id or urn returned by list_organizations, or the exact page name. Omit to target the personal profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/destructive=false, so the bar is lower; the description still adds real constraints — the post must be published, results are paginated, and for company pages the post urn must belong to that page. It does not describe the return shape in detail, but no output schema exists to cover that.
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 behavior and the default targeting are front-loaded, and the company-page constraint follows as a necessary caveat. 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 paginated read tool with full schema coverage and safe annotations, the description covers scope, targeting, and the company-page constraint. The only soft spot is return-shape detail (which fields accompany each author), which has no output schema to fall back on.
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 parameter documentation is already handled and the baseline is 3. The description adds genuine semantics beyond the schema: the default personal-profile targeting and the requirement that a company-page post urn belongs to that page.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource ("Retrieves the comments and their authors for a published LinkedIn post") and adds the pagination scope. The resource is clearly separable from siblings like get_post_likers and get_post, so an agent can select it 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 explicit targeting guidance: personal profile by default, pass `organization` for a company page, and it routes the agent to list_organizations for valid values. It stops short of naming when a caller should prefer a different sibling tool, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the people and organizations who liked a LinkedIn post, with pagination. Works on the personal profile by default; pass organization to target a company page (see list_organizations). For a company page, the post urn must belong to that page.
| Name | Required | Description | Default |
|---|---|---|---|
| urn | Yes | LinkedIn URN of the post | |
| limit | No | Number of likers to return | |
| offset | No | Number of likers to skip | |
| organization | No | LinkedIn company page to act on instead of the personal profile. Pass the page id or urn returned by list_organizations, or the exact page name. Omit to target the personal profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds behavior beyond that: pagination is supported and a company-page target imposes an urn-ownership constraint. It does not cover failure modes (e.g., private posts, hidden likers), keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with what is retrieved, followed by target-selection behavior and the constraint. Every clause earns its place with no repetition of schema content.
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, 4-parameter tool with full schema coverage and annotations but no output schema, the description covers purpose, target selection, and pagination. It could say more about what each liker record contains, though annotations and the absence of an output schema lower that burden.
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 four parameters are already documented in the schema; the baseline here is 3. The description reinforces the organization parameter's dual-target behavior and names list_organizations as the source of the value, but adds no format or syntax detail 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 ('Retrieves the people and organizations who liked a LinkedIn post') and adds scope ('with pagination'), which cleanly separates it from the adjacent get_post_commenters sibling. An agent can tell exactly what comes back 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 default behavior ('works on the personal profile by default; pass organization to target a company page'), routes the agent to list_organizations for the id, and adds a prerequisite ('the post urn must belong to that page'). It stops short of explicitly contrasting with the likers-vs-commenters choice, so it is strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Computes a statistical summary of LinkedIn posts over a given period: averages, totals and best-performing posts. Works on the personal profile by default; pass organization to target a company page (see list_organizations).
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | No | End date in ISO 8601 format | |
| startDate | No | Start date in ISO 8601 format | |
| organization | No | LinkedIn company page to act on instead of the personal profile. Pass the page id or urn returned by list_organizations, or the exact page name. Omit to target the personal profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds meaningful context about target scoping and what the computation produces (averages, totals, best-performing posts). It does not discuss rate limits, latency, or caveats on sparse data, but for a read-only aggregate that is minor.
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 capability is front-loaded before the scoping detail. Every clause carries information the agent needs.
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 statistic tool with no output schema, the description gives a usable picture of the returned content (averages, totals, best-performing posts) and the target scoping. Only the precise shape of 'best-performing' and date-range defaulting remain 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 coverage is 100%, so all three parameters including the ISO 8601 date formats and the organization id/urn/name forms are documented in the schema itself. The description only restates the organization override and adds a cross-reference to list_organizations, 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 ('computes a statistical summary of LinkedIn posts') plus the scope ('over a given period'), which clearly separates it from list_posts and get_post. An agent can identify it as an aggregate-analysis tool 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?
Specifies the default target (personal profile) and the condition for the alternative target (pass `organization` for a company page), pointing to list_organizations for the id. It does not say when to prefer this summary over list_posts or search_posts, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists LinkedIn post drafts with, for each, whether it targets the personal profile or a company page. Can filter by status: all, unscheduled drafts, scheduled, or already published. Works on the personal profile by default; pass organization to target a company page (see list_organizations).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of drafts to return | |
| offset | No | Number of drafts to skip | |
| status | No | Filter by status: all, draft (not scheduled), scheduled, published | all |
| organization | No | LinkedIn company page to act on instead of the personal profile. Pass the page id or urn returned by list_organizations, or the exact page name. Omit to target the personal profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the default-scope behavior (personal profile unless organization is passed), which is genuinely useful, but says nothing about ordering, result volume, or pagination behavior beyond what the 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?
Three sentences, front-loaded with the purpose and then routing/scope details. Slightly wordier than necessary in the first clause ('with, for each, whether it targets...'), but every sentence carries usable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description partially compensates by noting that each result indicates profile vs. company page targeting. Annotations cover the read-only profile, and the filter/targeting mechanics are covered; only return shape and pagination defaults are left implicit.
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 itself documents limit, offset, status, and organization — including the list_organizations reference. The description reinforces the status filter and the organization default but adds no syntax or 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 ('Lists LinkedIn post drafts') and adds the distinguishing payload detail that each entry reports whether it targets the personal profile or a company page. That differentiates it from list_posts and list_organizations 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?
Explicitly states the default target (personal profile) and the condition that switches to a company page ('pass organization'), plus the available status filters. It doesn't name a when-not case or a competing sibling that should be used instead, 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.
Lists the LinkedIn company pages (organizations) the user administers in PerfectPost, with the user's rights on each. Call it before creating a draft or reading posts for a company page: the other tools take the returned id, urn or name as their organization parameter. Reading a page's posts is open to everyone (last 28 days without Premium); posting on a page requires PerfectPost Premium.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context on top: returned rights per page, the returned identifiers (id/urn/name), the 28-day non-Premium read window, and that posting requires PerfectPost Premium. It stops short of describing pagination or result ordering.
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 followed by usage and the access caveat; each sentence carries information. Minor redundancy in 'company pages (organizations)' and the paywall sentence is helpful but slightly tangential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must carry the return story, and it does at a high level (id/urn/name, rights). Combined with the dependency guidance and access rules, an agent has enough to call this correctly; only pagination/result-shape details are absent.
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?
Zero input parameters, so the baseline is 4. The description usefully characterizes the data the call surfaces (id, urn, name, rights), though that is return-value semantics rather than parameter 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 (Lists) and resource (LinkedIn company pages/organizations) plus scope (those the user administers) and even the return content (rights per page). An agent can distinguish it from list_posts, list_drafts, and get_linkedin_profile 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?
Explicitly tells the agent when to call it: before creating a draft or reading posts for a company page, because sibling tools consume the returned id/urn/name as their `organization` parameter. That is a concrete prerequisite and dependency, not an implied one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists published LinkedIn posts with their full engagement metrics, media and metadata. Supports pagination and date filtering. Works on the personal profile by default; pass organization to target a company page (see list_organizations).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of posts to return | |
| offset | No | Number of posts to skip | |
| endDate | No | End date in ISO 8601 format | |
| startDate | No | Start date in ISO 8601 format | |
| organization | No | LinkedIn company page to act on instead of the personal profile. Pass the page id or urn returned by list_organizations, or the exact page name. Omit to target the personal profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond that: the default personal-profile scope, company-page targeting via `organization`, and that pagination and date filtering are supported.
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 what the tool returns and followed by filtering and scope behavior. No filler; each sentence carries a distinct fact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully names the return contents (posts with engagement metrics, media, metadata) and covers pagination, date filtering, and scope. Only a summary of return ordering or shape 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% and every parameter is documented in the schema itself. The description only restates the `organization` default behavior already spelled out in the schema, so it adds 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 and resource ('Lists published LinkedIn posts') and enumerates what comes back (engagement metrics, media, metadata). 'Published' implicitly separates it from the draft tools, but it never explicitly contrasts itself with search_posts or get_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 the default scope and how to switch to a company page via `organization`, and notes pagination/date support. It does not say when to prefer this over sibling list/search tools like search_posts or get_posts_stats_summary, so usage is only partially guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schedules a draft for automatic publication on LinkedIn at a specific date and time. The date must be in the future. Company-page drafts are re-checked against the user's current rights on the page (and Premium) before scheduling.
| Name | Required | Description | Default |
|---|---|---|---|
| draftId | Yes | The identifier of the draft to schedule | |
| programmingDate | Yes | Publication date and time in ISO 8601 format (e.g. 2025-03-15T09:00:00Z) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag the operation as a non-readOnly, destructive, open-world write. The description adds genuine context beyond them: the future-date constraint and the authorization detail that company-page drafts are re-checked against current page/Premium rights before scheduling. It does not, however, say what happens on failure or whether an already-scheduled draft can be rescheduled.
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 core action and platform, followed by the two constraints. 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?
For a 2-parameter mutation tool with no output schema, the description covers the action, timing constraint, and rights-check behavior. Annotations carry the safety profile. Minor gaps remain around failure behavior and rescheduling semantics, but nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters documented, so the baseline is 3. The description adds a constraint the schema lacks — the programmingDate must be in the future — which is meaningful semantic value beyond the ISO 8601 format note in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Schedules a draft') plus the target platform and effect ('automatic publication on LinkedIn at a specific date and time'). This is clearly distinguishable from sibling tools like create_draft, update_draft, and update_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?
Provides real preconditions ('date must be in the future') and a mode-specific caveat about company-page drafts, but never names an alternative tool or states when not to use this one (e.g., to publish immediately or edit an existing scheduled draft). Usage context 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.
Searches the text of LinkedIn posts. Useful for finding posts on a specific topic. Works on the personal profile by default; pass organization to target a company page (see list_organizations).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results | |
| query | Yes | Text to search for in posts | |
| organization | No | LinkedIn company page to act on instead of the personal profile. Pass the page id or urn returned by list_organizations, or the exact page name. Omit to target the personal profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds useful scoping behavior (defaults to personal profile, org override). It says nothing about pagination, result caps, or return shape, which is a modest gap for a search tool.
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 what the tool does, then usage, then the targeting rule. Every sentence carries information 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?
For a read-only search with full schema coverage and annotations covering safety, the description supplies the needed targeting context. The only real omission is how results are returned or capped, which is minor since no output schema exists and limits are documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented in the schema; baseline is 3. The description restates the organization override that the schema already explains and adds no new syntax or format detail beyond it.
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 ('Searches the text of LinkedIn posts') and clarifies the searchable surface is post text, which meaningfully separates it from get_post/list_posts. It does not explicitly name or contrast with those siblings, so it falls just 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 clear context ('finding posts on a specific topic') and states the default target (personal profile) plus the override case (pass organization), pointing to list_organizations for the id. No explicit when-not-to-use guidance or alternative-tool routing, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decodes a base64-encoded image and attaches it to an existing draft. Use this tool ONLY for images shared directly in the conversation as attachments (not a public URL). For PDF documents and videos, use set_draft_media_from_url with a public URL instead (e.g. from Canva, Google Drive, or any public hosting).
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Base64-encoded image content (without the data:…;base64, prefix) | |
| type | Yes | Media type — images only. For PDF/video, use set_draft_media_from_url. | |
| title | No | Media title (optional) | |
| altText | No | Alt text for the image (optional) | |
| draftId | Yes | The draft identifier | |
| mimeType | Yes | MIME type of the image, e.g. image/png, image/jpeg, image/gif, image/webp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the agent knows this is a mutating operation. The description adds useful context (attachment-based input, decode behavior, existing-draft requirement) but does not disclose what the destructive flag implies — e.g. whether attaching replaces existing draft media or what happens on failure. With annotations carrying the safety profile, this is a modest but real addition.
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 with no filler, and the core action plus its scope ('existing draft') is front-loaded ahead of the routing guidance. Every clause either defines the operation or routes the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter, no-output-schema mutation tool, the description covers input mode, target resource, and alternatives adequately, and the schema covers all parameters fully. The only meaningful gap is the unstated effect on pre-existing draft media, which the destructive annotation hints at but does not explain.
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 includes the base64 prefix caveat, MIME type format, and the enum constraint on type. The description adds no parameter-level syntax beyond what the schema already states, 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: decodes base64 image and attaches it to an existing draft. It explicitly distinguishes itself from the sibling set_draft_media_from_url, so an agent can route correctly without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit ONLY condition ('images shared directly in the conversation as attachments') and an explicit exclusion with the alternative named for PDF/video ('use set_draft_media_from_url with a public URL'). When-to-use and when-not-to-use are both covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Downloads a media file from a public URL (image, video or PDF, e.g. from Canva) and attaches it to an existing draft.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public URL of the media to download | |
| type | Yes | Media type | |
| title | No | Media title (optional) | |
| altText | No | Alt text for images (optional) | |
| draftId | Yes | The draft identifier |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the write/mutation profile is covered by structured data. The description adds the useful detail that content is fetched remotely from a public URL, but omits what 'destructive' means here (does it replace existing draft media?), size/type limits, and failure behavior on unreachable URLs.
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 the action, source, supported formats, and target all front-loaded; no redundant or filler text.
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 mutation with no output schema, the description covers the basic mechanics but not the consequences (overwrite vs append of existing draft media) or the effect on draft state. It is adequate but leaves the main behavioral question unanswered.
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 five parameters including the enum for type are already documented in the schema. The description adds only the media-type enumeration and URL source context, which the schema largely conveys; 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 ('Downloads a media file from a public URL and attaches it to an existing draft'), which is precise and agent-actionable. It does not name or differentiate itself from the sibling set_draft_media_from_base64, which is the closest alternative, so it falls 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?
There is no guidance on when to use this tool versus set_draft_media_from_base64 or update_draft. The parenthetical 'e.g. from Canva' hints at the source scenario but does not state conditions, prerequisites (media must already exist in a draft), or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates the content or metadata of an existing unpublished draft. Only the provided fields are updated. Pass organization to move the draft to a company page, or clearOrganization to move it back to the personal profile. Works on the personal profile by default; pass organization to target a company page (see list_organizations).
| Name | Required | Description | Default |
|---|---|---|---|
| poll | No | Poll to attach to the draft (replaces any existing media) | |
| title | No | New title | |
| content | No | New content in HTML | |
| draftId | Yes | The identifier of the draft to update | |
| objective | No | Marketing objective: tofu (awareness), mofu (consideration), bofu (conversion) | |
| categories | No | New categories/tags | |
| organization | No | LinkedIn company page to act on instead of the personal profile. Pass the page id or urn returned by list_organizations, or the exact page name. Omit to target the personal profile. | |
| clearOrganization | No | Set to true to move a company-page draft back to the personal profile. | |
| scheduledComments | No | Comments to post automatically under the publication, each with its own delay | |
| scheduledReshares | No | Reshares of the post to schedule, each with its own delay |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds genuinely useful behavioral context beyond that: patch semantics ('Only the provided fields are updated') and the relocation behavior of organization/clearOrganization. It does not mention permission needs or that attaching a poll replaces existing media, so it is not complete.
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 in the first sentence and the sentences are short. The organization/default-target sentence is partly redundant with the preceding `organization`/`clearOrganization` sentence, which slightly dilutes it.
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 mutation tool with nested poll/scheduledComments/scheduledReshares objects and no output schema, the description covers the primary call shape and targeting rules. The complex nested scheduling parameters are left entirely to the schema, which is acceptable given full schema coverage but leaves the description a bit thin.
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 baseline is 3. The description goes beyond the schema by explaining the default targeting rule and the interactive behavior of organization vs clearOrganization, which the schema documents only separately.
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 ('Updates the content or metadata of an existing unpublished draft'). The qualifier 'unpublished draft' cleanly separates it from the sibling update_post, so an agent can route 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 the operating context: works on the personal profile by default, and pass `organization` to act on a company page, pointing to list_organizations for ids. It does not name explicit exclusions or contrast against update_post/schedule_draft, but the when-to-use context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates the metadata of a published post (marketing objective, categories, favorite). Only the provided fields are updated. Works on the personal profile by default; pass organization to target a company page (see list_organizations).
| Name | Required | Description | Default |
|---|---|---|---|
| urn | Yes | LinkedIn URN of the post to update | |
| favorite | No | Mark or unmark the post as favorite | |
| objective | No | Marketing objective: tofu (awareness), mofu (consideration), bofu (conversion) | |
| categories | No | Categories or tags associated with the post | |
| organization | No | LinkedIn company page to act on instead of the personal profile. Pass the page id or urn returned by list_organizations, or the exact page name. Omit to target the personal profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds real context beyond annotations: partial-update behavior and profile-vs-organization targeting. But with destructiveHint=true, the highest-value missing detail is what actually gets destroyed or replaced — e.g. whether passing `categories` replaces the existing list or appends to it. That gap is left entirely to 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 tight sentences, zero waste. The core action and update semantics come first, then the targeting default and the sibling pointer — properly 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, so the description would need to carry return behavior; it does not describe the response. Combined with an unexplained destructiveHint=true and no statement about merge-vs-replace semantics for list fields, the definition is adequate but leaves real behavioral questions unanswered.
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 five parameters are already documented in the schema, including the `organization` default. The description repeats the org-targeting rule but adds no syntax or 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 ('Updates the metadata of a published post') and enumerates the mutable fields (marketing objective, categories, favorite). The word 'published' implicitly separates it from the sibling update_draft, so an agent can route correctly 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?
Explains partial-update semantics ('Only the provided fields are updated') and gives a clear default-vs-alternative rule for targeting: personal profile by default, pass `organization` for a company page, with a pointer to list_organizations. It stops short of explicit when-not-to-use guidance or preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
create_draft1 field changedInput schema / properties / scheduledReshares / items / properties / organizationAdded value: +{
+ "description": "Company page that reshares the post instead of the personal profile (page id, urn or exact name, see list_organizations). Requires Premium and post rights on the page.",
+ "type": "string"
+}update_draft1 field changedInput schema / properties / scheduledReshares / items / properties / organizationAdded value: +{
+ "description": "Company page that reshares the post instead of the personal profile (page id, urn or exact name, see list_organizations). Requires Premium and post rights on the page.",
+ "type": "string"
+}create_draftget_draftget_linkedin_profileget_postget_post_commentersget_post_likersget_posts_stats_summarylist_draftslist_organizationslist_postsschedule_draftsearch_postsset_draft_media_from_base64set_draft_media_from_urlupdate_draftupdate_postMCP server for QPost — lets AI agents publish video and image posts to YouTube, TikTok, Instagram.
Managed LinkedIn MCP server for AI agents: search, connect, message and enrich on accounts you own.
LinkedIn actions for AI agents: search, messaging, posts and invites, as hosted MCP tools.
Social media MCP server: your Instagram, TikTok, YouTube, LinkedIn and Threads history for your AI.
Add one secure layer between your agents and this server.
