gads_impression_share
Analyze campaign impression share and identify if budget or Quality Score/bid is limiting reach by retrieving lost impression share metrics per campaign.
Instructions
Search Impression Share, Lost IS (Budget), and Lost IS (Rank) per campaign. Identifies whether budget or Quality Score/bid is limiting reach.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | No | Override GOOGLE_ADS_CUSTOMER_ID for this call | |
| start_date | No | Start date: YYYY-MM-DD, NdaysAgo, yesterday, or today | 28daysAgo |
| end_date | No | End date: YYYY-MM-DD, NdaysAgo, yesterday, or today | yesterday |
Implementation Reference
- src/tools/performance.ts:80-103 (handler)Main handler function that executes the 'gads_impression_share' tool logic. Queries Google Ads API for impression share metrics per campaign including search impression share, budget lost IS, rank lost IS, exact match IS, content impression share, and content lost IS.
export async function impressionShare(args: z.infer<z.ZodObject<typeof impressionShareSchema>>) { const customer = getCustomer(args.customer_id); const start = resolveDate(args.start_date); const end = resolveDate(args.end_date); const rows = await customer.query(` SELECT campaign.id, campaign.name, campaign.advertising_channel_type, metrics.search_impression_share, metrics.search_budget_lost_impression_share, metrics.search_rank_lost_impression_share, metrics.search_exact_match_impression_share, metrics.content_impression_share, metrics.content_budget_lost_impression_share, metrics.content_rank_lost_impression_share FROM campaign WHERE segments.date BETWEEN '${start}' AND '${end}' AND campaign.status = 'ENABLED' ORDER BY metrics.search_impression_share ASC LIMIT 200 `); return { rowCount: rows.length, rows }; } - src/tools/performance.ts:76-78 (schema)Schema definition for the impression share tool. Extends baseArgs (customer_id, start_date, end_date) with Zod validation.
export const impressionShareSchema = { ...baseArgs, }; - src/index.ts:197-202 (registration)Registers the 'gads_impression_share' tool with the MCP server, binding the schema and handler function.
server.tool( "gads_impression_share", "Search Impression Share, Lost IS (Budget), and Lost IS (Rank) per campaign. Identifies whether budget or Quality Score/bid is limiting reach.", impressionShareSchema, async (args) => { try { return ok(await impressionShare(args)); } catch (e) { return err(e); } } ); - src/tools/performance.ts:4-8 (helper)Shared baseArgs definition (customer_id, start_date, end_date) used by impressionShareSchema.
const baseArgs = { customer_id: z.string().optional().describe("Override GOOGLE_ADS_CUSTOMER_ID for this call"), start_date: z.string().default(DEFAULT_START).describe("Start date: YYYY-MM-DD, NdaysAgo, yesterday, or today"), end_date: z.string().default(DEFAULT_END).describe("End date: YYYY-MM-DD, NdaysAgo, yesterday, or today"), };