linkedin-campaign-manager-mcp
LinkedIn 广告系列管理器 MCP
用于 LinkedIn Marketing API 的 MCP 服务器 — 可通过 Claude 用纯英语查询广告系列、效果和潜在客户开发表单。
包含 19 个只读工具，涵盖广告账户、广告系列、创意、效果分析、受众特征、视频分析、预算进度、周期对比、转化、潜在客户开发表单、受众和定向维度。专为在 LinkedIn 上运行赞助内容、潜在客户开发表单和基于账户的广告系列的 B2B 付费社交团队打造。
为什么存在此项目
LinkedIn Marketing API 的使用体验非常糟糕：每月一次的 Rosetta 版本更新、缺乏文档的字段映射、用于分析的 Rest.li 风格嵌套查询参数，以及会静默过期的 60 天访问令牌。此服务器在后台处理了所有这些复杂性，因此您可以用纯英语提问，而无需手动编写 dateRange=(start:(year:...))。
目前没有其他开源的 LinkedIn 广告 MCP 服务器能达到这种深度。大多数服务器仅止步于“列出广告系列”。本项目包含受众特征、视频完成漏斗、预算进度、周期对比以及带有 PII（个人身份信息）的潜在客户开发表单响应，以便您可以将潜在客户与 Marketo 或 Salesforce 进行核对。
示例提示词
安装后，您可以向 Claude 询问如下问题：
“过去 28 天我们的 LinkedIn 广告支出趋势如何，按广告系列组细分？”
“对比本月与上月竞争对手征服广告系列的 CPL（潜在客户获取成本）——哪些创意推动了数据增长？”
“提取我们支出最高的广告系列的受众特征——哪些资历和行业的人在转化？”
“上个月哪些潜在客户开发表单的提交率最高，每个潜在客户的成本是多少？”
“展示我们品牌认知广告系列的视频完成漏斗——用户在哪里流失了？”
“是否有任何广告系列面临超支风险？显示所有活跃广告系列的预算进度。”
“提取昨天的潜在客户开发表单响应，以便我可以将其与 Marketo 进行抽查核对。”
演示
🎥 演示视频即将推出 — 在 60 秒内通过 Claude Code 查询 LinkedIn 广告系列效果。
工具
工具 | 功能 |
| 用户可访问的所有广告账户，包含状态和货币。 |
| 单个账户详情：货币、状态、类型、账单信息。 |
| 账户中的广告系列；可按状态或广告系列组筛选。 |
| 完整的广告系列详情：定向标准、出价、预算、目标。 |
| 广告系列组（共享预算/目标容器）。 |
| 广告创意；可按广告系列或状态筛选。 |
| 完整的创意详情：标题、文案、URL、图片/视频 URN。 |
| 指定日期范围内的展示次数/点击次数/支出/转化次数/潜在客户数。支持 DAILY/MONTHLY/YEARLY/ALL 粒度。 |
| 按公司/公司规模/行业/职能/职位/资历/地区/国家划分的效果。 |
| WoW/MoM/YoY 对比，服务器端计算每个实体的 _current/_prior/_delta/_pct_change 列。 |
| 每个创意的视频完成漏斗：开始 → 25% → 50% → 75% → 完成 + 完成率。 |
| 在可配置周期内，活跃广告系列的支出与预算使用百分比。 |
| Insight Tag 转化事件定义：类型、归因窗口、启用状态。 |
| 按转化事件（CONVERSION 维度）划分的效果：点击后转化与浏览后转化细分。 |
| DMP 分段：匹配受众、公司列表、组合/类似受众分段 + 大小。 |
| 定向值的即时搜索（职位、技能、公司、行业、地点、资历）。 |
| 潜在客户开发表单 + 问题配置 + 状态。 |
| 包含 PII（姓名、电子邮件、公司、职位）的实际表单提交数据。 |
| 每个创意的 LGF 指标：表单打开率、提交率、每个潜在客户成本。 |
设置
1. 安装
npm install -g linkedin-campaign-manager-mcp或者克隆并本地构建：
git clone https://github.com/ZLeventer/linkedin-campaign-manager-mcp
cd linkedin-campaign-manager-mcp
npm install
npm run build2. 创建 LinkedIn 开发者应用
Marketing API 是受限的。您需要一个具有特定产品批准的 LinkedIn 开发者应用：
前往 developer.linkedin.com → 创建应用（关联到您的公司主页）。
产品选项卡 — 请求访问：
Marketing Developer Platform（涵盖r_ads,r_ads_reporting）Lead Gen Forms或Community Management API（涵盖r_ads_leadgen_automation）
LinkedIn 会手动审核应用访问权限 — 通常需要 2–6 周。
Auth 选项卡 → 授权重定向 URL — 添加：
http://127.0.0.1:53123（如果您设置了不同的LINKEDIN_OAUTH_PORT，请相应更改53123）。从 Auth 选项卡复制 Client ID 和 Client Secret。
如果没有产品批准，每个 API 调用都会返回 403。服务器可以正常编译和启动 — 403 是应用级别的权限问题，而非代码问题。
3. 配置环境变量
cp .env.example .env
# edit .env with your LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET,
# LINKEDIN_DEFAULT_AD_ACCOUNT (numeric ID from Campaign Manager URL)4. 授权（一次性 OAuth 流程）
npm run auth这会在端口 53123（或 LINKEDIN_OAUTH_PORT）上打开一个本地 HTTP 服务器，将授权 URL 打印到您的终端，并等待 OAuth 回调。在浏览器中批准后，它会将代码交换为访问令牌 + 365 天刷新令牌，并将其保存到 token.json（模式 0600）。
只有在刷新令牌过期（365 天后）时，才需要重新运行 npm run auth。
5. 连接到 Claude Code（或任何 MCP 客户端）
在 ~/.claude.json 的 mcpServers 下添加：
{
"mcpServers": {
"linkedin": {
"command": "linkedin-campaign-manager-mcp",
"env": {
"LINKEDIN_CLIENT_ID": "your_client_id",
"LINKEDIN_CLIENT_SECRET": "your_client_secret",
"LINKEDIN_TOKEN_PATH": "/absolute/path/to/token.json",
"LINKEDIN_DEFAULT_AD_ACCOUNT": "123456789",
"LINKEDIN_API_VERSION": "202504"
}
}
}
}或者如果从源码运行：
{
"mcpServers": {
"linkedin": {
"command": "node",
"args": ["/path/to/linkedin-campaign-manager-mcp/dist/index.js"],
"env": {
"LINKEDIN_CLIENT_ID": "...",
"LINKEDIN_CLIENT_SECRET": "...",
"LINKEDIN_TOKEN_PATH": "/path/to/token.json",
"LINKEDIN_DEFAULT_AD_ACCOUNT": "123456789"
}
}
}
}重启 Claude Code。19 个工具将出现在 linkedin 服务器下。
环境变量
变量 | 必需 | 默认 | 描述 |
| 是 | — | OAuth 应用客户端 ID |
| 是 | — | OAuth 应用客户端密钥 |
| 否 |
| 读取/写入令牌文件的路径 |
| 推荐 | — | 数字账户 ID；当未传递 |
| 否 |
| OAuth 重定向的环回端口 |
| 否 |
| LinkedIn Rosetta API 版本 (YYYYMM) |
URN 处理
LinkedIn 资源由 URN 标识：urn:li:sponsoredAccount:123, urn:li:sponsoredCampaign:456 等。
所有工具输入都接受纯数字 ID 或完整 URN — 客户端会自动包装纯数字 ID。数字 ID 出现在广告系列管理器 URL 中 (/accounts/<id>/, /campaigns/<id>/)。
日期输入
所有日期参数接受：
输入 | 含义 |
| 字面 ISO 日期 |
| 不言自明 |
| 今天之前的 N 个日历日 |
默认范围：28daysAgo → yesterday。
LinkedIn 特有的注意事项
API 版本更迭
LinkedIn Rosetta 使用月度版本（202504 = 2025 年 4 月）。版本在发布约 12 个月后弃用 — 届时您会收到 410 Gone 错误。请每季度更新 LINKEDIN_API_VERSION。请参阅 版本控制文档。
分析查询格式
/adAnalytics 使用 Rest.li 风格的嵌套参数，而非纯 ISO 字符串：
dateRange=(start:(year:2024,month:10,day:1),end:(year:2024,month:10,day:31))
campaigns=List(urn:li:sponsoredCampaign:123,urn:li:sponsoredCampaign:456)这在内部由 dateRangeParam() 和 liGetRaw() 处理。如果您扩展服务器，请通过 liGetRaw() 使用手动构建的 URL 路由分析调用 — 不要对分析端点使用 liGet()，因为 URLSearchParams 会破坏嵌套的括号。
分析数据延迟
LinkedIn 分析数据对于大多数指标通常有 2–6 小时的延迟，对于转化数据则长达 24 小时。昨天的数字通常是完整的；今天的数字是部分的。
60 天访问令牌，365 天刷新令牌
访问令牌在 60 天后过期；刷新令牌在 365 天后过期。客户端在需要时会在每次请求时自动刷新访问令牌。如果刷新令牌过期，请再次运行 npm run auth。
潜在客户开发响应 PII
li_get_leadgen_responses 返回实际的潜在客户 PII — 姓名、电子邮件、公司、职位。请将输出视为敏感信息：不要写入共享日志、未加密的存储或公共渠道。LinkedIn 的数据使用政策要求在收到潜在客户后的 90 天内删除响应，除非潜在客户明确同意。此工具旨在用于授权的 CRM 核对（Marketo/SFDC）。
速率限制
LinkedIn 不发布硬性速率限制数字。在实践中，预计每个应用每分钟约 100 次分析调用会受到限制。未内置 429 重试机制 — 如果达到限制，请降低调用频率或在客户端缓存结果。
何时不应使用此服务器
创建或编辑广告系列、预算或创意 — 设计上为只读。广告系列创建有太多的失败模式，无法安全自动化；请使用广告系列管理器 UI。
实时展示数据 — 使用 LinkedIn Insight Tag + GA4 获取近乎实时的数据。
针对任意定向标准的受众规模估算 — 使用广告系列管理器受众构建器 UI 进行临时估算。
li_get_audience_insights仅返回已保存/上传分段的规模。
许可证
MIT © 2026 Zach Leventer
Available Tools
19 toolsli_compare_periodsA
Compare LinkedIn campaign performance across two time periods. wow (week-over-week): last 7d vs prior 7d. mom (month-over-month): last 30d vs prior 30d. yoy (year-over-year): last 30d vs same 30d last year. Returns per-entity rows (keyed by campaign/creative URN) with _current, _prior, _delta, and _pct_change columns for every requested metric. Deltas are computed server-side so you do not need to post-process. Useful for weekly/monthly performance reports and anomaly detection.
| Name | Required | Description | Default |
|---|---|---|---|
| pivot | No | CAMPAIGN | |
| fields | No | ||
| comparison | No | wow: last 7d vs prior 7d. mom: last 30d vs prior 30d. yoy: last 30d vs same 30d last year. | wow |
| campaign_ids | No | ||
| ad_account_id | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries full burden. States it returns per-entity rows with delta columns and that deltas are computed server-side. Does not mention read-only status or rate limits, but for a comparison tool this is adequate.
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?
Concise 4 sentences with no fluff. Front-loads purpose, then details modes, output, and use cases. Effectively communicates without excess.
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, description adequately explains return structure. Sufficient for agent to understand tool's niche among siblings. Could mention required parameters (none required) but overall 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 low (20%). Description adds meaning for 'comparison' enum and 'fields' (implicitly). Does not detail 'campaign_ids' or 'ad_account_id', but these are standard in LinkedIn tools. Some value added beyond 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?
Describes a specific action: comparing campaign performance across two time periods. Clearly distinguishes from sibling tools like li_get_campaign_performance which likely returns single-period data.
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 when to use (weekly/monthly reports, anomaly detection) and details the three comparison modes. Does not explicitly mention when not to use, but context is clear enough for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_get_accountA
Get full details for a single LinkedIn ad account, including currency code, status, account type (BUSINESS/ENTERPRISE), total budget, billing info, and the associated organization URN. Useful for confirming account currency before interpreting spend data, or checking billing status before troubleshooting ad delivery issues.
| Name | Required | Description | Default |
|---|---|---|---|
| ad_account_id | No | Ad account numeric ID or URN (urn:li:sponsoredAccount:123). Defaults to LINKEDIN_DEFAULT_AD_ACCOUNT. The numeric ID is visible in Campaign Manager URLs: /accounts/<id>/. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavioral traits. It does not mention that the operation is read-only, any authentication requirements, rate limits, or error conditions. This leaves the agent without critical safety context.
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 redundancy. Purpose is front-loaded, usage guidance follows. Every word adds value, making it concise and well-structured.
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 tool with no output schema, the description adequately covers what it returns and when to use it. It could be enhanced by mentioning the output structure more explicitly, but the listed fields suffice.
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% for the single parameter, and the description does not add significant new meaning beyond what the schema provides. Baseline of 3 is appropriate given the schema already describes the parameter well.
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 clearly states the tool retrieves full details for a single LinkedIn ad account, listing specific fields like currency, status, account type, etc. It distinguishes from sibling tools like li_list_ad_accounts (list vs detail).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: useful for confirming account currency before interpreting spend data or checking billing status before troubleshooting. While no when-not-to or alternatives are mentioned, the usage scenarios are clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_get_audience_insightsA
List DMP (Data Management Platform) segments attached to a LinkedIn ad account. Segments represent matched audiences (USER type: contact list uploads, website retargeting, lookalike audiences) and company lists (COMPANY type: for account-based marketing). Returns segment name, type, source, estimated size (where LinkedIn reports it), and status. Use to audit available audiences before building campaigns, or to confirm a matched audience uploaded successfully and has enough members to serve ads.
| Name | Required | Description | Default |
|---|---|---|---|
| ad_account_id | No | ||
| type | No | Filter segment type: USER (contact list / matched audience), COMPANY (company list for ABM), COMBINED (combined / lookalike segment). | |
| page_size | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return fields (name, type, source, estimated size, status) and the 'where LinkedIn reports it' nuance. Without annotations, this provides necessary behavioral insight, though pagination is not mentioned (implied by page_size parameter).
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 main action, no redundancy. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains return fields and usage. It lacks error handling details but covers essential aspects for a list operation.
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 33% (only 'type' has schema description). The description reinforces the 'type' enum values from the schema but adds no extra meaning for 'ad_account_id' or 'page_size'. It partially compensates by explaining the tool's output context.
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 clearly states 'List DMP segments attached to a LinkedIn ad account' and explains segment types (USER, COMPANY). This verb-resource pair is specific and distinct from sibling tools.
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 provides two use cases: auditing audiences before campaigns and confirming upload success. It gives context but does not exclude alternatives or mention when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_get_budget_pacingA
Calculate budget utilization for active LinkedIn campaigns. Compares spend over the specified period_days window against total or estimated period budget, and returns a utilization_pct for each campaign. Useful for mid-flight pacing checks: if utilization is below 80% near the end of a month, the campaign may be under-delivering; above 100% means it is over-pacing. Accepts optional campaign_ids to limit scope; defaults to all ACTIVE campaigns in the account.
| Name | Required | Description | Default |
|---|---|---|---|
| ad_account_id | No | ||
| campaign_ids | No | Limit pacing report to these campaigns. Omit to report all active campaigns in the account. | |
| period_days | No | Number of days to look back for spend. Should match your budget period (e.g., 30 for monthly). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses the core behavior: compares spend over period_days, returns utilization_pct, operates on active campaigns. It is a read-only analytic, so safety is implied. No contradictions.
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: first defines purpose, second explains logic, third provides usage examples. Every sentence is essential and front-loaded. No unnecessary details.
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 explains the return value (utilization_pct per campaign) and the underlying logic. It covers inputs, behavior, and output adequately for a simple analytic tool. The complexity is low, and the description is self-contained.
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 covers 67% of parameters with descriptions; the description adds context for period_days (should match budget period) and campaign_ids (defaults to all active). For ad_account_id, which lacks schema description, the description does not cover it, but it's a standard parameter. The description adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates budget utilization for active LinkedIn campaigns, specifying it compares spend and returns utilization percentage. This distinguishes it from sibling tools like li_get_campaign_performance, which provides general performance metrics.
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 explicit guidance on when to use: mid-flight pacing checks with thresholds (below 80% under-delivering, above 100% over-pacing). Also explains optional campaign_ids and default scope. Could be improved by mentioning alternatives like li_get_campaign_performance for other metrics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_get_campaignA
Get complete detail for a single LinkedIn campaign, including the full targetingCriteria object (all included/excluded facets), bid strategy, unit cost, daily/total budget, run schedule, objective, optimization target, format, and locale. Use this when you need to audit targeting setup, diagnose budget configuration, or confirm campaign structure before pulling performance data.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | Campaign numeric ID or URN (urn:li:sponsoredCampaign:123). Required. | |
| ad_account_id | No | Ad account numeric ID or URN. Defaults to LINKEDIN_DEFAULT_AD_ACCOUNT. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states what is returned (full detail) but does not explicitly declare that the tool is read-only or has no side effects. However, the context implies a read operation, and the description is transparent about the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action and details, and the second sentence provides usage context. Every word is necessary and informative.
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?
Despite no output schema, the description lists many returned fields (targetingCriteria, bid strategy, budget, etc.), giving a complete picture of what the agent can expect. For a tool with moderate complexity, this is thorough.
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 input schema already covers both parameters with descriptions. The description adds value by noting that campaign_id is required and ad_account_id defaults to LINKEDIN_DEFAULT_AD_ACCOUNT, providing operational context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool retrieves 'complete detail for a single LinkedIn campaign' and enumerates specific elements like targetingCriteria, bid strategy, etc., clearly distinguishing it from sibling tools like li_get_campaign_performance.
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 provides clear guidance on when to use the tool: 'audit targeting setup, diagnose budget configuration, or confirm campaign structure before pulling performance data.' This helps an agent select the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_get_campaign_performanceA
Fetch performance metrics for LinkedIn campaigns over a date range. Returns impressions, clicks, spend (USD and local currency), website conversions, one-click lead form submissions, landing-page clicks, video views, follows, reactions, comments, and shares. Pass campaign_ids for specific campaigns or use ad_account_id for account-level totals. Supports DAILY/MONTHLY/YEARLY/ALL time granularity and CAMPAIGN/CAMPAIGN_GROUP/CREATIVE/ACCOUNT pivots. Default range: last 28 days.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_ids | No | Campaign numeric IDs or URNs. Omit to report at account level. | |
| ad_account_id | No | Ad account ID/URN. Used when campaign_ids is omitted. Defaults to LINKEDIN_DEFAULT_AD_ACCOUNT. | |
| start_date | No | Start of date range. Accepts YYYY-MM-DD, today, yesterday, or NdaysAgo. Default: 28daysAgo. | 28daysAgo |
| end_date | No | End of date range. Default: yesterday. | yesterday |
| time_granularity | No | ALL | |
| pivot | No | CAMPAIGN | |
| fields | No | Comma-separated metrics. Default: impressions,clicks,costInUsd,costInLocalCurrency,externalWebsiteConversions,oneClickLeads,landingPageClicks,videoViews,follows,reactions,comments,shares |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses default date range (last 28 days) and list of returned metrics. Implies read-only operation. Does not mention auth requirements or rate limits, but for a read tool this is acceptable.
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?
One paragraph of 4 sentences, each sentence packed with meaningful information. Front-loaded with purpose and key metrics, then parameter usage. 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?
No output schema, but description enumerates all returned metrics. Covers all 7 parameters with usage context. Explains aggregation levels (pivots) and date ranges. Complete for a read tool with no side effects.
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 71%. Description adds context beyond schema: explains the role of campaign_ids, ad_account_id, default dates, and lists default fields. Helps understand parameter behavior without reading 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?
Description clearly states verb 'Fetch performance metrics' for 'LinkedIn campaigns over a date range.' Lists specific metrics and parameters, distinguishing it from siblings like li_get_campaign (which would return campaign details).
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 guidance on when to use campaign_ids vs ad_account_id, and default date range. Supports various time granularities and pivots. However, does not explicitly mention when not to use or alternative sibling tools like li_get_conversion_performance for conversion-specific metrics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_get_conversion_eventsA
List LinkedIn conversion event definitions on an ad account. Returns each event's name, type (URL/FILE_DOWNLOAD/SIGN_UP/etc.), enabled status, attributionType, post-click and view-through attribution window sizes, and associated Insight Tag. These are the events tracked by the LinkedIn Insight Tag on your website. Use to audit conversion event setup, confirm event names before pulling conversion performance, or verify attribution window configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| ad_account_id | No | Ad account numeric ID or URN. Defaults to LINKEDIN_DEFAULT_AD_ACCOUNT. | |
| enabled_only | No | If true, only return enabled conversion events. Set false to include disabled/archived events. | |
| page_size | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose read-only nature, authentication requirements, rate limits, or pagination behavior. The description is straightforward but lacks explicit behavioral warnings or details beyond the function.
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?
Description is three sentences with no wasted words: first sentence states purpose, second enumerates return fields, third lists use cases. Well front-loaded and efficient.
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, description adequately explains return values (name, type, enabled status, attributionType, attribution windows, Insight Tag). It covers typical use cases but could mention pagination implications (page_size parameter) and prerequisites (ad account access). Minor gaps.
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 67% (ad_account_id and enabled_only have descriptions). The description does not add significant parameter-level details beyond the schema; it lists return fields rather than elaborating on parameters like page_size. Baseline score of 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?
Description clearly states it lists LinkedIn conversion event definitions on an ad account, and enumerates return fields. This distinguishes it from sibling tools like li_get_conversion_performance which return performance data, not definitions.
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?
Description explicitly states use cases: audit conversion event setup, confirm event names before pulling conversion performance, verify attribution window configuration. It does not explicitly exclude other uses or mention alternatives, but provides clear context for when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_get_conversion_performanceA
Fetch conversion performance broken down by conversion event (CONVERSION pivot). Returns externalWebsiteConversions, externalWebsitePostClickConversions, externalWebsitePostViewConversions, impressions, clicks, and spend per conversion event. Use to compare cost-per-conversion across event types, diagnose which Insight Tag events are driving value, or build a funnel from impression → click → conversion. Scope to specific campaigns or report at account level.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_ids | No | Campaign numeric IDs or URNs to scope the conversion report. Omit for account-level. | |
| ad_account_id | No | ||
| start_date | No | Start of date range. Accepts YYYY-MM-DD, today, yesterday, or NdaysAgo. Default: 28daysAgo. | 28daysAgo |
| end_date | No | yesterday | |
| fields | No | Comma-separated metrics. Default: externalWebsiteConversions,externalWebsitePostClickConversions,externalWebsitePostViewConversions,impressions,clicks,costInUsd,costInLocalCurrency |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full responsibility. It clearly states the operation is a read fetch and lists the returned metrics. However, it omits details like rate limits, data freshness, auth requirements, or any side effects. For a read-only tool, this is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: core action first, then return fields, then use cases, then scoping. Each sentence adds value, though it could be slightly shorter. The front-loading is effective for quick agent parsing.
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 fairly explains return values by listing the metrics and their meaning. It also covers the pivot dimension. It does not mention pagination, data limits, or error handling, but for a report tool with moderate complexity, the coverage is mostly 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 60%. The description adds only minor repetition of scoping guidance for campaign_ids ('Scope to specific campaigns or report at account level'). It offers no additional meaning for parameters like ad_account_id, end_date, or fields beyond what is in the schema, and does not compensate for the 40% of parameters lacking schema descriptions.
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 specifies a clear verb ('Fetch'), resource ('conversion performance'), and unique breakdown ('by conversion event'). It lists specific metrics returned and provides concrete use cases (compare cost-per-conversion, diagnose event value, build funnel). This effectively distinguishes it from sibling campaign-performance tools.
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 scoping options ('Scope to specific campaigns or report at account level') and describes when to use (comparing cost-per-conversion, diagnosing event value, building funnels). No explicit when-not-to-use or alternatives, but the guidance is sufficient for an agent to select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_get_creativeA
Get full detail for a single LinkedIn ad creative, including the creative content (headline, body copy, destination URL, image/video URNs, call-to-action label), intendedStatus, associated campaign URNs, and creative type. Use when auditing ad copy and creative assets, debugging a rejected creative, or pulling the landing page URL to cross-reference with GA4 UTM data.
| Name | Required | Description | Default |
|---|---|---|---|
| creative_id | Yes | Creative numeric ID or URN (urn:li:sponsoredCreative:123). Required. | |
| ad_account_id | No | Ad account numeric ID or URN. Defaults to LINKEDIN_DEFAULT_AD_ACCOUNT. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description fully discloses returned fields (content, status, campaign URNs, type). No mention of rate limits or auth, but sufficient for a read operation.
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 purpose, no redundant words. Every sentence provides essential 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, but description enumerates key return fields. Lacks error handling details, but covers primary use case comprehensively.
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%; description adds value by specifying 'numeric ID or URN' for creative_id and default value for ad_account_id, beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with a specific verb+resource ('Get full detail for a single LinkedIn ad creative') and lists included fields, clearly differentiating from sibling listing tools like li_list_creatives.
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 use cases: auditing ad copy, debugging rejected creatives, cross-referencing URLs. Does not mention when not to use, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_get_demographics_reportA
Break down LinkedIn campaign performance by a demographic dimension of the people who saw or clicked your ads. Pivot options: MEMBER_JOB_TITLE (which titles engage most), MEMBER_JOB_FUNCTION, MEMBER_SENIORITY (director vs. manager vs. C-suite), MEMBER_COMPANY (which accounts clicked), MEMBER_COMPANY_SIZE, MEMBER_INDUSTRY, MEMBER_COUNTRY_V2, MEMBER_REGION_V2. Returns impressions, clicks, spend, leads, and conversions per dimension value. Useful for buyer-persona fit analysis and ABM account-list validation.
| Name | Required | Description | Default |
|---|---|---|---|
| pivot | Yes | Demographic dimension to break down by. MEMBER_JOB_TITLE / MEMBER_JOB_FUNCTION / MEMBER_SENIORITY are useful for persona fit; MEMBER_COMPANY / MEMBER_COMPANY_SIZE for ABM audience analysis; MEMBER_INDUSTRY for vertical benchmarking; MEMBER_COUNTRY_V2 / MEMBER_REGION_V2 for geo reporting. | |
| campaign_ids | No | ||
| ad_account_id | No | ||
| start_date | No | 28daysAgo | |
| end_date | No | yesterday | |
| fields | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It explains that the tool returns impressions, clicks, spend, leads, and conversions per dimension value, but does not disclose behavioral traits like required permissions, data freshness, pagination, or handling of multiple campaigns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (6 sentences) and well-structured, front-loading the purpose, listing options with context, stating return metrics, and ending with use cases. No superfluous 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?
Given the tool has 6 parameters (5 undocumented in both schema and description), no output schema, and moderate complexity, the description omits critical context for filtering (campaign_ids, ad_account_id, date range) and does not explain the response structure beyond listing metrics.
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 description adds significant value for the pivot parameter by explaining each enum value and grouping them by use case, supplementing the schema's 17% coverage. However, it provides no semantics for other parameters like campaign_ids, ad_account_id, start_date, end_date, and fields.
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 clearly states the tool's purpose: breaking down LinkedIn campaign performance by a demographic dimension. It lists all pivot options and distinguishes itself from siblings like li_get_campaign_performance by focusing on demographic breakdowns and specific use cases (buyer-persona fit, ABM).
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 provides clear usage contexts for each pivot option (e.g., persona fit, ABM analysis, geo reporting) and implies when to use the tool but does not explicitly state when not to use it or mention alternatives like li_get_campaign_performance for overall metrics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_get_leadgen_form_performanceA
Fetch LinkedIn Lead Gen Form performance analytics broken down by creative. Returns impressions, clicks, Lead Gen Form opens (oneClickLeadFormOpens), lead submissions (oneClickLeads), spend, and computed metrics: formOpenRate (opens / clicks), leadSubmitRate (submissions / opens), costPerLead (spend / submissions), and CTR. Use to identify high-performing LGF creatives, diagnose drop-off between form open and submission, or compare cost-per-lead across campaigns.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | yesterday | |
| start_date | No | Start of date range. Default: 28daysAgo. | 28daysAgo |
| campaign_ids | No | Scope to specific campaigns (pass campaign IDs or URNs). Omit to report across all campaigns in the account. | |
| ad_account_id | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the breakdown by creative and computed metrics, which aids transparency. However, it does not mention non-obvious behaviors like pagination, rate limits, authorization needs, or data freshness, which would be helpful for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the action and metrics, followed by use cases. No redundant or unnecessary information. Every sentence is purposeful and efficient.
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 annotations or output schema, the description is fairly complete: it explains what metrics are returned and provides use cases. However, it leaves ambiguity about how the breakdown by creative is structured and does not explain the role of ad_account_id or the default behavior of date parameters. Still, it covers the core purpose well.
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 50% (2 of 4 parameters have descriptions). The description does not add information for the undocumented parameters (end_date, ad_account_id), nor does it clarify parameter usage beyond what the schema provides. It does not compensate for the missing schema descriptions, leaving the agent unclear about these parameters.
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 clearly states the tool fetches LinkedIn Lead Gen Form performance analytics broken down by creative, listing specific metrics (impressions, clicks, opens, submissions, spend, and computed metrics like formOpenRate). It also differentiates from siblings like li_get_leadgen_forms (which lists forms) and li_get_leadgen_responses (which gets individual responses) by focusing on performance analytics.
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 provides explicit use cases: 'identify high-performing LGF creatives, diagnose drop-off between form open and submission, or compare cost-per-lead across campaigns.' It implies when to use the tool but does not specify when not to use or directly compare with alternatives. However, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_get_leadgen_formsA
List LinkedIn Lead Gen Forms on an ad account. Returns form name, state (ACTIVE/DRAFT/ARCHIVED), the list of questions asked (field type, label, pre-fill source), the thank-you page URL and message, and the associated landing page (if any). Use to audit form question setup, confirm form state before troubleshooting lead delivery, or verify which forms are attached to active campaigns.
| Name | Required | Description | Default |
|---|---|---|---|
| ad_account_id | No | ||
| state | No | Filter by form state. ACTIVE forms are live on ads. DRAFT forms are not yet submitted for review. | |
| page_size | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description correctly implies read-only behavior by stating it 'lists' and 'returns' data. It does not disclose potential pagination or rate-limiting behavior. The description is adequate but not exhaustive for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences: first states purpose, second lists returns, third gives use cases. No redundant information, and the purpose 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?
Given no output schema, the description covers the main return values (name, state, questions, thank-you page, landing page). It lacks details on pagination metadata or any potential empty results. Overall, it is mostly complete for a list 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?
The input schema has 33% description coverage (only state has a description). The description adds context for the state parameter (e.g., 'ACTIVE forms are live on ads'), but does not elaborate on ad_account_id or page_size. Coverage is low, but the description partially compensates for state.
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 starts with the specific verb 'List' and resource 'LinkedIn Lead Gen Forms on an ad account'. It enumerates returned fields (name, state, questions, thank-you page, landing page) and provides distinct use cases (audit form setup, confirm state, etc.). This clearly distinguishes it from sibling tools like li_get_campaign or li_get_leadgen_responses.
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 lists three concrete scenarios (audit form setup, confirm state before troubleshooting, verify attached forms) that indicate when to use the tool. However, it does not explicitly state when not to use it or provide alternatives, which would make it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_get_leadgen_responsesA
Retrieve actual Lead Gen Form submission data from LinkedIn. Each response includes questionResponses with field-by-field values (first name, last name, email, company, job title, phone, etc.) and submission timestamp. Filter by lead_form_id and/or submitted_after/before date range. Use for lead-to-CRM reconciliation against SFDC or Marketo, for auditing lead quality, or for confirming that a form integration is capturing the right fields. NOTE: This endpoint returns PII — handle output as sensitive data.
| Name | Required | Description | Default |
|---|---|---|---|
| ad_account_id | No | ||
| lead_form_id | No | Filter to a specific Lead Gen Form (numeric ID or URN). | |
| submitted_after | No | ISO date (YYYY-MM-DD). Only include responses submitted on or after this date. | |
| submitted_before | No | ISO date (YYYY-MM-DD). Upper bound for submission date. | |
| page_size | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It warns about PII and sensitive data handling, and describes the response structure. However, it lacks details on rate limits, authentication requirements, or pagination behavior for a tool with 5 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and front-loaded with the core action. Every sentence adds value, 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?
The description explains the return values (questionResponses with fields and timestamp) and data sensitivity, which is crucial with no output schema. It lacks pagination details but is otherwise complete for the tool's purpose.
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 description mentions filtering by lead_form_id and date range, adding meaning to those parameters. However, it does not mention ad_account_id or page_size. Schema coverage is 60%, so description compensates partially but not fully.
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 clearly states it retrieves Lead Gen Form submission data from LinkedIn, specifying the resource and the verb ('Retrieve'). It distinguishes itself from sibling tools like li_get_leadgen_forms (which lists forms) by focusing on responses.
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 provides explicit use cases: lead-to-CRM reconciliation, auditing lead quality, and confirming form integration. It does not mention when not to use or compare to siblings, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_get_video_analyticsA
Fetch video-specific performance metrics for LinkedIn campaigns, broken down by creative. Returns videoStarts, videoViews, videoFirstQuartileCompletions, videoMidpointCompletions, videoThirdQuartileCompletions, videoCompletions, plus a computed videoCompletionRate (completions / starts × 100). Use to evaluate video ad quality — high completion rates indicate compelling content; low rates signal drop-off. Scope to specific campaigns via campaign_ids or report at account level.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_ids | No | Campaign numeric IDs or URNs to scope the report. Omit to report at account level. | |
| ad_account_id | No | ||
| start_date | No | 28daysAgo | |
| end_date | No | yesterday | |
| time_granularity | No | ALL |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes what data is returned but does not mention side effects, rate limits, auth requirements, or whether it is read-only (though implied). Basic transparency is present but lacks depth.
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 with no fluff. The first sentence front-loads purpose and return fields, the second gives usage guidance, and the third explains scoping. Every sentence is essential and well-structured.
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 and moderate complexity, the description covers return metrics, interpretation, and scoping. Missing details like response format, pagination, or time zone handling. Still fairly complete for a read-only analytics 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 only 20% (one parameter described). The description adds value by explaining campaign_ids: 'Scope to specific campaigns via campaign_ids or report at account level.' However, other parameters (ad_account_id, dates, time_granularity) receive no explanation. The description partially compensates for low schema coverage but not fully.
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 clearly states it fetches video-specific performance metrics for LinkedIn campaigns, broken down by creative. It lists specific metrics and distinguishes from sibling tools like li_get_campaign_performance by specifying 'video-specific' and 'broken down by creative'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases: 'Use to evaluate video ad quality — high completion rates indicate compelling content; low rates signal drop-off.' It also explains scoping options via campaign_ids or account level. However, it does not mention when not to use this tool or compare directly with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_list_ad_accountsA
List all LinkedIn ad accounts the authenticated user has access to. Returns account ID, name, status, currency, type (BUSINESS/ENTERPRISE), and reference organization URN. Use this first to discover the ad_account_id needed by other tools. Filter by status (ACTIVE/CANCELED/DRAFT/PENDING_DELETION/REMOVED) or omit to see all accounts.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by ad account status. Omit to return accounts in all statuses. | |
| page_size | No | Number of results per page (max 100). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It adequately describes the tool as a read-only list operation, details the returned data, and mentions filtering. However, it does not disclose pagination behavior beyond the page_size parameter, rate limits, or authentication specifics beyond 'authenticated user.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (two sentences plus a filter note), front-loaded with the core purpose, and every sentence adds value. There is no redundancy or unnecessary detail.
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 or annotations, the description covers the tool's purpose, return fields, usage context, and parameter options. It lacks details on cursor-based pagination or error handling, but for a simple list tool with two optional params, it is sufficiently 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 coverage is 100%, so baseline is 3. The description reiterates the status filter and its options (including the default of showing all statuses when omitted), which adds marginal context but doesn't significantly supplement the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all LinkedIn ad accounts accessible to the user, specifies returned fields (ID, name, status, currency, type, reference organization URN), and distinguishes itself from siblings like li_get_account by focusing on listing multiple accounts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises 'Use this first to discover the ad_account_id needed by other tools,' providing clear guidance on when to use this tool. It also explains the optional status filter and its effect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_list_campaign_groupsA
List campaign groups in a LinkedIn ad account. Campaign groups are containers that group related campaigns under a shared name and optional total budget cap. Returns group name, status, total budget, run schedule, and the campaigns count. Use to understand account structure before pulling campaign-level data.
| Name | Required | Description | Default |
|---|---|---|---|
| ad_account_id | No | ||
| status | No | ||
| page_size | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It mentions the returned fields but omits details like pagination behavior, error handling, authentication requirements, or rate limits. The description is adequate for a simple list operation but lacks comprehensive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose and output, then usage guidance. No redundant or extra words. Every sentence adds value and is easy to parse quickly.
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 and moderate complexity (3 params), the description lacks parameter details and pagination behavior. It covers purpose and output fields partially but not fully. It is usable but leaves the agent with unanswered questions for robust 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?
With 0% schema description coverage, the description must explain parameters. It does not mention ad_account_id, status, or page_size at all. The only hint is 'in a LinkedIn ad account' implying ad_account_id, but no details on usage, default, or enum meanings. This is a critical gap.
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 clearly states the tool lists campaign groups in a LinkedIn ad account, defines what campaign groups are, and specifies the returned fields (name, status, total budget, run schedule, campaigns count). It distinguishes from siblings by advising use before pulling campaign-level data, making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'Use to understand account structure before pulling campaign-level data,' providing a clear context. It lacks explicit alternatives or when-not-to-use guidance, but the context is strong enough to guide selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_list_campaignsA
List campaigns in a LinkedIn ad account. Returns campaign name, status, objectiveType (WEBSITE_VISITS/LEAD_GENERATION/BRAND_AWARENESS/etc.), optimizationTargetType, bid amount, daily/total budget, run schedule, and targeting criteria summary. Filter by status or campaign_group_id. Use li_get_campaign for full targeting detail on a specific campaign.
| Name | Required | Description | Default |
|---|---|---|---|
| ad_account_id | No | Ad account numeric ID or URN. Defaults to LINKEDIN_DEFAULT_AD_ACCOUNT. | |
| status | No | Filter by campaign status. Omit to return campaigns in all statuses. | |
| campaign_group_id | No | Filter to campaigns belonging to a specific campaign group (numeric ID or URN). | |
| page_size | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description implies a read operation by listing campaigns, but does not explicitly state read-only behavior, rate limits, or pagination details. It returns specific fields but not the output format (e.g., array).
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 main action, followed by returned data and filtering/alternative. Every sentence adds value without 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?
The description covers the tool's purpose, inputs, and outputs sufficiently for a listing tool. However, it does not explicitly state the output is an array or mention pagination or sorting behavior. The return fields are listed but not structured.
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 75% (3 of 4 parameters described). The description mentions filtering by status and campaign_group_id, adding context to those parameters. However, it does not describe page_size or ad_account_id further, and the schema already covers parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'List' with the resource 'campaigns in a LinkedIn ad account', making the action and scope clear. It also distinguishes itself from sibling li_get_campaign by noting that the latter provides full targeting detail.
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 states filtering options (status, campaign_group_id) and explicitly recommends li_get_campaign for full targeting detail. It lacks an explicit 'when not to use' statement, but the alternative is clearly given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_list_creativesA
List ad creatives in a LinkedIn ad account. Returns creative content type (SPONSORED_STATUS_UPDATE/MESSAGE/etc.), intendedStatus, associated campaigns, and content URNs. Filter by campaign_id to see all creatives on a specific campaign, or by status to find paused/archived ads. Use li_get_creative for full content detail on a specific creative.
| Name | Required | Description | Default |
|---|---|---|---|
| ad_account_id | No | ||
| campaign_id | No | Filter to creatives in a specific campaign (numeric ID or URN). | |
| status | No | Filter by intendedStatus. | |
| page_size | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Describes returned fields and filtering behavior. Lacks mention of pagination beyond page_size parameter, rate limits, or error handling, but overall is transparent about the tool's read-only nature and output.
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 concise sentences, front-loaded with purpose, no redundancy. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, and return fields adequately for a list tool with no output schema. Provides sibling guidance. Missing default ordering or pagination details (though page_size parameter exists), but overall sufficient.
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 already describes campaign_id and status well. Description adds practical usage context ('see all creatives on a specific campaign', 'find paused/archived ads'), enhancing parameter meaning beyond schema. However, does not elaborate on ad_account_id or page_size beyond 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?
Clearly states the verb 'List' and resource 'ad creatives in a LinkedIn ad account'. Explicitly lists return fields (creative content type, intendedStatus, campaigns, content URNs) and distinguishes from sibling li_get_creative, which provides full detail on a single creative.
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 explicit when-to-use guidance: filter by campaign_id or status. Directs to li_get_creative for detailed content, which prevents misuse and clarifies alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
li_search_targeting_facetsA
Search LinkedIn targeting facet values to find the correct URNs for audience targeting. Facets include: jobTitles (e.g., 'Supply Chain Director'), skills (e.g., 'S&OP'), companies, industries, seniorities, locations, and more. Returns matching facet values with their LinkedIn URNs, which can then be used to configure campaign targeting via the Campaign Manager UI. Useful for researching targeting options, confirming exact category names, or building audience documentation.
| Name | Required | Description | Default |
|---|---|---|---|
| facet | Yes | Targeting facet to search. Use jobTitles for job title targeting, skills for skill-based targeting, companies to find specific company targets, industries for vertical targeting, seniorities for seniority-level targeting, locations for geo targeting. | |
| query | Yes | Search string to filter facet values. Example: 'supply chain' for jobTitles. | |
| locale | No | Locale for facet label localization. Default: en_US. | en_US |
| count | No | Maximum number of matching facet values to return (max 50). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states the tool returns matching facet values with URNs, implying a read-only operation, but does not explicitly confirm idempotence or mention rate limits or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and structured with bullet-like examples. Every sentence adds value without 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?
The description provides sufficient context for a search tool, but lacks details on the return format (e.g., object structure) and pagination. Given no output schema, a bit more on return values would improve completeness.
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 schema covers all parameters, but the description adds value by listing example facets and explaining how results are used for campaign targeting, enhancing understanding beyond the schema details.
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 clearly states the tool searches LinkedIn targeting facet values to find URNs for audience targeting. It lists specific facets and use cases, distinguishing it from sibling get/list tools.
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 the tool is useful for researching targeting options and building audience documentation, providing clear context. It does not explicitly state when not to use it or list alternatives, but the sibling set lacks other search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
19 tool updates
v1.0.0- First observed
li_compare_periods - First observed
li_get_account - First observed
li_get_audience_insights - First observed
li_get_budget_pacing - First observed
li_get_campaign - First observed
li_get_campaign_performance - First observed
li_get_conversion_events - First observed
li_get_conversion_performance - First observed
li_get_creative - First observed
li_get_demographics_report - First observed
li_get_leadgen_form_performance - First observed
li_get_leadgen_forms - First observed
li_get_leadgen_responses - First observed
li_get_video_analytics - First observed
li_list_ad_accounts - First observed
li_list_campaign_groups - First observed
li_list_campaigns - First observed
li_list_creatives - First observed
li_search_targeting_facets
TDQS
Scored across 19 tools
Each tool has a clearly distinct purpose: listing vs. getting details vs. performance reports vs. conversion/leadgen analytics vs. targeting research. Even similar-looking tools like li_get_campaign_performance, li_get_leadgen_form_performance, and li_get_conversion_performance target different metric types and dimensions, so an agent can reliably pick the right one.
All tools follow a consistent snake_case pattern with the li_ prefix and verb-noun structure (list_, get_, search_, compare_). The naming is highly predictable: li_list_* for enumeration, li_get_* for details or reports, and specific modifiers like _performance, _analytics, _insights. No mixed conventions or irregular verbs.
At 19 tools, this is slightly above the typical 3-15 range but still well-justified for the complexity of LinkedIn advertising. Each tool covers a distinct aspect (accounts, campaigns, creatives, performance, demographics, video, conversions, audiences, leadgen, targeting, pacing, comparison) without redundancy. The count feels reasonable for the domain's depth.
The toolset is heavily read/analytics-focused: it covers listing, getting details, and detailed performance/reporting for all major entities, but lacks any create, update, or delete operations for campaigns, creatives, or account settings. For a 'campaign manager' one might expect lifecycle management, but as a monitoring/analytics surface it is fairly complete. The gaps are significant if the intended scope includes editing, but for reporting and optimization analysis it works well.
Maintenance
Related MCP Connectors
Hosted LinkedIn MCP server that connects your own LinkedIn account to Claude, ChatGPT, Cursor, n8n and any MCP client. 33 tools: people and Sales Navigator search, profiles, companies, jobs, inbox, posts, invites, email and phone finding. Free 7-day trial, no card (connecting your own LinkedIn account needs a paid plan). Starter $19/month, Pro $49/month, Max $199/month. $10 top-ups.
Managed LinkedIn MCP server for AI agents: search, connect, message and enrich on accounts you own.
LinkedIn outreach MCP server — 19 tools for AI agents to prospect, sequence, and manage contacts.
LinkedIn Ads MCP server: 10 tools for campaigns, creatives, audiences, lead forms. Writes preview.
