key-identification

Key Identification

When a user asks what key a chord progression is in, call ga_key_identify. Do NOT analyze the progression from training knowledge — the diatonic-set match is pitch-class arithmetic and the LLM is unreliable at it.

Calling the tool

The tool takes one argument:

• query — string. Either a bare chord list ("C Am F G") or the user's full question ("what key is C Am F G in?"). The tool extracts chord symbols from prose.

It returns a structured result:

• RecognizedChords — string array, what the parser actually saw (useful for catching typos).
• TopCandidates — array of KeyCandidateInfo. Keys tied at the highest match count.
• PartialMatches — up to 3 partial-match keys ranked behind the top set.
• TotalChords — total chords parsed.
• Error — non-null when no chords parsed or no candidates matched.

Each KeyCandidateInfo has:

• Key — canonical key name (e.g. "C major", "A minor").
• RelativeKey — name of the relative pair.
• MatchCount / TotalChords — N of M chords are diatonic in this key.
• DiatonicSet — the seven diatonic chords (I through vii°) in order.

Phrasing the answer

Your job is to explain the key choice in guitarist-friendly language. Use the structured tool result; do NOT add analysis the tool didn't compute.

Single top candidate

When TopCandidates has exactly one entry: lead with the key name and the match score, give the Roman numeral function of each input chord, and mention the diatonic set.

The progression Dm G C is in C major (3/3 chords diatonic). In C major: Dm = ii, G = V, C = I — a classic ii-V-I cadence. The diatonic chords of C major are C – Dm – Em – F – G – Am – B°.

Tied candidates (relative-pair ambiguity)

When TopCandidates has multiple entries (almost always 2 — the relative major/minor pair share a diatonic set): name both, then explain how to distinguish them by ear.

The progression C Am F G fits C major AND A minor equally — both contain all four chords. To tell them apart, listen for the tonic: if the progression keeps resolving to C as home, it's C major; if Am feels like home, it's A minor. The relative-key pair shares the diatonic set C – Dm – Em – F – G – Am – B°.