Google Ads Quality Score tool planner

What it does

Quality Score is Google's 1 to 10 rating of a keyword. A low score can make clicks cost more. The score has three parts: expected click rate, ad relevance and landing page experience. The fix for each part is different, so you need to know which part is weak before you change anything. This prompt briefs your coding AI to build a Quality Score review. It reads keyword rows, drops the tiny ones, and sorts the rest with an eight-row table that covers every mix of weak and fine parts. It then groups them by ad group and cause, so thirty keywords with the same problem become one action. A keyword with no part ratings is listed as not evaluated, never as healthy. All the cost bands and the spend floor are settings you set. The module only reads and recommends. It never changes a keyword or an ad.

What goes in and out

You give it

• A code project and a coding AI, such as Claude Code, that can edit it
• Keyword rows with cost, Quality Score and its three part ratings, from the Google Ads API or sample rows
• The date range and account currency
• Your spend floor and cost bands for severity (optional, the prompt gives starting values)

You get

• A prompt that builds one read-only review function with typed input and output
• An eight-row table that diagnoses every mix of weak and fine parts
• One finding per ad group and cause, ranked by spend, with a fix for each
• A summary with the share of spend on low Quality Score, and keywords listed as not evaluated
• Tests on sample rows, with no real account used

How the task works

• Looks at your project. Finds your language, test setup and any existing fetch code or result type, and reports what is missing.
• Drops the small and the unrated. Removes keywords below your spend floor. Keywords with no part ratings are counted as not evaluated.
• Diagnoses each keyword. Uses an eight-row table of expected click rate, ad relevance and landing page. An average rating counts as not flagged.
• Groups by ad group and cause. Makes one finding per group, with the affected keywords listed, ranked by total cost.
• Sets severity and a fix. Maps cost to severity with your bands and gives a starting fix for each cause.
• Writes the summary and tests. Gives the spend share on low Quality Score with its sums, and tests every row of the table.

Full instructions

• Decide where keyword data comes from. If you have code that fetches it, tell the AI where it is. If not, the prompt builds the function to take typed rows.
• Copy the prompt from the skill and fill in the angle brackets, including your spend floor and cost bands. Paste it into your coding AI with your project open.
• Read what the AI says about your project first. If it lists missing pieces, decide whether to add them or build without them.
• Check the thresholds it lists. The spend floor and cost bands are starting guesses, so set your own before you trust the severity labels. Then run the tests on sample rows.
• Run it on a live account only when you decide to, read-only. Review monthly, not weekly.
• Use the fixes as a to-do list for your ads and landing pages. Nothing is changed for you.

Change the instructions

• Your spend floor. Set it near what a keyword must cost before it is worth fixing. A floor that is too low fills the report with dust.
• Your cost bands. Set them in your own currency and for your account size. The starting values are only a guide.
• Your date range. Use at least a few weeks. Quality Score changes slowly, so short ranges show little.
• Part ratings. Keywords with no ratings are listed as not evaluated. More data in the range means fewer of them.

Words used in this task

• Quality Score: Google's 1 to 10 rating of a keyword, based on three parts.
• Expected click rate: How likely your ad is to be clicked for this keyword, compared with others.
• Ad relevance: How well your ad matches what the person searched for.
• Landing page experience: How useful and fast the page is for someone who clicks your ad.
• Read-only: The code can look at data but cannot change keywords, ads or accounts.

Full instruction file

Quality Score review coding prompt

This is a prompt you paste into a coding AI (Claude Code, Cursor, Codex or similar) that can read and edit your project. It builds one read-only module that reviews Google Ads Quality Score keyword by keyword and groups the problems by cause.

Quality Score is Google's 1 to 10 rating of a keyword. It has three parts: expected click rate, ad relevance and landing page experience. Each part is rated below average, average or above average. The module reads those parts and tells you which one to fix first.

If you only want a review of your own numbers, not software, use the Google Ads store account auditor.

Before you start

Use the material below to do this job. If facts or tool access are missing, explain what you can finish and what must wait.

What you need (use your own material or the linked skill):

• A codebase (yours): a project's code, in a folder or repo the AI can open.

How to start:

1. Look first. Use what they've already attached, pasted or put in their about-me note. In a coding assistant with file access, look in the project too for these by name.
2. Check what's missing. Look for a codebase. They can attach files, paste the details, or share a file path your assistant can read. Ask only for missing facts that change the result. If they ask you to start with what they have, complete the parts you can and mark the gaps.
3. Do the job. Follow the method with the facts and tools you have. Mark each gap with MISSING: where it belongs and never invent a fact to fill it. Keep the answer tight: say each point once and merge steps that give the same thing. In CHECKS MISSED, list checks that failed or could not run. If every required check ran and passed, write “none”.

What you need first

• A project with code you can edit, and a coding AI with access to it.
• Keyword data for a date range, with cost, the Quality Score and its three parts. Google Ads gives you these through its API. Fetching them live needs a Google Ads API developer token and read access to the account. Setting that up is a separate job: see the Google Ads token and access check planner. Without access, the prompt builds the module to take typed keyword rows, so it still works and can be tested on sample rows.
• A spend floor: the cost below which a keyword is too small to bother with. Pick one that suits your account. The prompt starts at 25 in your account currency.
• Cost bands for severity: the spend levels that mean critical, high, medium and low. The prompt starts with sample bands. They are starting guesses, not facts about your account. Set your own before you trust the severity labels.
• Enough keywords for the result to mean something. A small account may only produce a handful of groups. That is fine.

Paste this into your coding AI

Fill in the angle brackets first.

Build a read-only Quality Score review module that groups Google Ads keywords by what is dragging their Quality Score down and says what to fix first. It must never change a keyword, ad or account.

First, look at my project: language, folder layout, how tests run, whether a result type for findings already exists, and whether code already fetches Google Ads keyword data. Tell me what you found. If something I need is missing, list it and build the part that does not depend on it.

## What to build

Function: reviewQualityScore(input) returns DiagnosticOutput. Put it in <the folder where my analysis code lives>, in my project's language and style.

Input:
- keywords: rows of { keywordText, adGroup, campaign, cost, qualityScore, expectedCtr, adRelevance, landingPageExperience }
  The three parts are one of BELOW_AVERAGE, AVERAGE, ABOVE_AVERAGE, or null when Google gave no rating.
- dateRange and currency
- minSpendForFlag: configurable, starts at <25> in account currency. A starting assumption I must review.
- maxKeywordsPerGroup: configurable, starts at 50. Only caps how many are listed.
- severityBands: configurable cost bands for severity, starting at critical above <1000>, high <250 to 1000>, medium <50 to 250>, low below <50>, in account currency. Starting assumptions I must review.

If the project has no result type yet, use:
  Finding = { checkId, severity: critical|high|medium|low|info, title, recommendation, affectedKeywords, evidence }
  DiagnosticOutput = { findings, summary, notEvaluated, dateRange, currency }

## Steps
1. Drop keywords with cost below minSpendForFlag. Count them as "below the spend floor" in the summary.
2. A keyword with null in any of the three parts is "not evaluated". Never call it healthy. Count it and list how much spend it holds.
3. Treat AVERAGE as not flagged (the same as ABOVE). A keyword is flagged only for a BELOW part.
4. Diagnose each remaining keyword with this table. B means BELOW_AVERAGE. A means AVERAGE or ABOVE_AVERAGE.

   | Expected CTR | Ad relevance | Landing page | Diagnosis |
   |---|---|---|---|
   | B | B | B | complete-overhaul |
   | B | A | A | ctr-issue |
   | A | B | A | relevance-issue |
   | A | A | B | landing-page-issue |
   | B | B | A | ad-problem |
   | A | B | B | ad-plus-lp-issue |
   | B | A | B | ctr-plus-lp-issue |
   | A | A | A | healthy (no finding) |

   These eight rows cover every combination, so no fallback rule is needed.
5. Group by ad group and diagnosis. Make one finding per group, with the affected keywords listed. This turns "rewrite the same ad for 30 keywords" into one action.
6. Within each diagnosis, sort groups by total cost, highest first.
7. checkId is "qs-" plus the diagnosis. Severity comes from the group's total cost and severityBands.
8. Use these recommendation texts:
   - complete-overhaul: "Pause or rebuild. Split the ad group into single-theme groups, rewrite the ads and fix the landing page."
   - ctr-issue: "Test new ad copy. Check pinned headlines, add extensions, try keyword insertion."
   - relevance-issue: "Make the ads match the keywords more closely. Split the ad group by theme or add headlines that use the keyword."
   - landing-page-issue: "Check the landing page for speed, mobile use and whether it matches the keyword. Consider a category page instead of the home page."
   - ad-problem: "Rewrite the ads for this ad group."
   - ad-plus-lp-issue: "Both the ad and the landing page need work. Start with the landing page, which often moves the score most."
   - ctr-plus-lp-issue: "New ad copy and a landing page review. Do both soon if the cost is high."
   These are starting advice, not promises that the score will rise.

## Summary block
- distribution: count of keywords per diagnosis, plus healthy, below spend floor and not evaluated
- spendShareLowQs: the share of evaluated spend on keywords with Quality Score below 7. Show the numerator and denominator in money. If Quality Score is null for a keyword, leave it out and say how much spend that is.
- topGroups: ad group, diagnosis, cost, keyword count

## Tests
Write tests with sample rows only, no real accounts:
- each of the eight table rows at least once
- AVERAGE treated as not flagged
- null parts give "not evaluated", never healthy
- spend floor filter
- severity bands at their edges
- ad group roll-up and sort order

## Rules
- Read-only. Do not call the Google Ads API from this module. Fetching is separate.
- No findings for healthy keywords.
- Do not install packages, change config, add a schedule or run against a live account. Ask me first.
- Do not invent numbers. Say what you ran and what you did not.

## When you are done, show me
1. The function signature and types
2. A sample DiagnosticOutput from the test rows
3. The test results (say if you could not run them)
4. A list of the thresholds and assumptions I need to review

Check the result

• Keywords with no sub-score data are listed as not evaluated, not healthy.
• Every threshold is a setting you can see, with your own number in it.
• Nothing in the module can change an account.
• The tests pass on sample rows.

After it works

Quality Score moves slowly, so a monthly review is plenty. Weekly runs mostly show noise. Run the module on a live account only when you say so, and keep it read-only. If you want a monthly schedule, ask the AI to propose one, then approve it yourself.

Next, work down the findings from the top: fix the ads or landing page for the biggest group, then wait a few weeks and run the review again. To fetch live data, set up access first with the Google Ads token and access check planner.

After this

When you've handed it back, suggest what they could do next in one short question. It's a suggestion: if they're done, that's fine. Offer these, and say they can type their own:

• The Simple code coach. It takes the code change. If they pick one and that skill is added here, carry straight on with what you just made. If not, give the link and say what to bring.