> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recruitier.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding Match Scores

> Learn what match scores measure, how the four scoring dimensions work, how critical penalty caps prevent misleading scores, and how to use scores effectively for placements.

## Overview

Every job match in Recruitier comes with a score -- a percentage that represents how well the job aligns with the candidate's profile. But a number alone does not tell the full story. Behind each score is a breakdown across four evaluation dimensions, a location penalty calculation, potential critical mismatch caps, and a natural language explanation from the AI.

This guide explains what the score actually measures, how it is calculated step by step, and how to use it effectively to prioritize your outreach and maximize placements.

## What the Score Represents

The match score is a **weighted composite** of four evaluation dimensions, each capturing a different aspect of fit between the candidate and the job. The score is calculated by Gemini after analyzing both the candidate's full profile (CV text up to 8,000 characters, confirmed skills, experience level) and the complete job description (up to 6,000 characters).

The score ranges from **0% to 100%**, where:

* **100%** means a perfect match across all dimensions (extremely rare in practice -- requires exact alignment in skills, role, experience, and all secondary factors)
* **0%** means no alignment at all (these are filtered out during vector search before they ever reach scoring)

Most matches you see fall between **40% and 95%**. The vector search pre-filters for basic relevance, so truly irrelevant jobs rarely make it to the scoring stage.

## Scoring Dimensions

The AI evaluates each match across four dimensions independently, then combines them using configurable per-candidate weights.

### Role Fit (Default: 30% weight)

Role Fit measures how well the candidate's professional background aligns with what the job requires at a fundamental level. The AI considers:

* Does the candidate's current or recent **title** map to this role? ("Senior Python Developer" vs. "Python Backend Engineer" = high alignment; "Marketing Manager" vs. "Python Developer" = low alignment)
* Is the **seniority level** appropriate? (Junior candidate for a junior role = good; junior for a lead role = poor)
* Does the candidate's **career trajectory** point toward this type of position? (3 years of progressive backend development roles = strong trajectory for a senior backend position)
* Is the **domain** relevant? (FinTech experience for a FinTech role = bonus)

A high Role Fit score means the candidate would be a natural fit for this role based on their career history. A low Role Fit score means the role represents a significant departure from their experience.

<Note>
  **Critical cap**: If Role Fit scores below **0.30**, the overall match score is capped at **35%** regardless of other dimension scores. This prevents a scenario where a candidate with completely wrong experience (e.g., a chef) gets a high score for a software role just because they happen to have relevant hobby skills. A fundamentally wrong role cannot be compensated by other factors.
</Note>

### Skills Fit (Default: 35% weight)

Skills Fit is the **most heavily weighted** dimension. It evaluates:

* How many of the job's **required skills** does the candidate have?
* Are the candidate's **core skills** central to this job's requirements?
* Are there **critical skill gaps** that would make the candidate unsuitable?
* How many of the candidate's skills are actually **relevant** to this role?

The AI identifies specific strengths and gaps, which are displayed on match cards as:

* **Key matching points** (green badges) -- The strongest reasons the candidate fits the role (e.g., relevant skills, experience alignment)
* **Potential concerns** (orange badges) -- Issues to consider, such as missing required skills or experience gaps

These badges are displayed alongside the score, giving you immediate visibility into what makes the match strong and where the gaps are.

<Warning>
  **Critical cap**: If Skills Fit scores below **0.30**, the overall match score is capped at **45%**. This prevents a situation where a Senior Java Developer gets a high score for a Python/FastAPI position just because their seniority, experience, and secondary factors all align. Core skills alignment is non-negotiable for a meaningful match.
</Warning>

### Experience Fit (Default: 20% weight)

Experience Fit looks at the broader context of the candidate's experience beyond just skills and title:

* Does their **years of experience** match the job's expectations? (5 years for a "3-5 years required" role = perfect; 1 year for a senior role = mismatch)
* Is their **industry experience** relevant? (Banking experience for a banking tech role = strong; gaming experience = weaker)
* Do their **past projects and responsibilities** align with what this job entails? (Led a team of 5 vs. individual contributor expectations)
* Does their **work complexity** match? (Startup experience vs. enterprise-scale expectations)

This dimension helps distinguish between two candidates who might have the same skills but very different levels of practical experience and professional maturity.

### Secondary Fit (Default: 15% weight)

Secondary Fit captures additional factors that influence match quality but are not the primary drivers:

* **Education alignment** -- Does the candidate's degree match the job's education requirements? (MSc Computer Science for a role requiring a technical degree)
* **Certifications** -- Relevant certifications (AWS Certified, PMP, Scrum Master)
* **Industry-specific knowledge** -- Domain expertise beyond technical skills
* **Language requirements** -- Dutch proficiency for Dutch-speaking roles
* **Company culture indicators** -- Startup vs. enterprise mindset, team size expectations

These factors individually carry less weight but together can meaningfully affect the overall score. For some roles (e.g., regulated industries requiring specific certifications), secondary fit can be a decisive factor.

## Score Calculation Step by Step

The final score is calculated through a multi-step process:

### Step 1: AI Dimension Scoring

The AI evaluates each dimension independently and returns four scores between 0 and 1:

```
role_fit = 0.82
skills_fit = 0.85
experience_fit = 0.68
secondary_fit = 0.60
```

### Step 2: Weighted Combination

The dimension scores are combined using the candidate's configured weights (or defaults):

```
base_score = (role_fit x weight_role) + (skills_fit x weight_skills)
           + (experience_fit x weight_experience) + (secondary_fit x weight_secondary)

base_score = (0.82 x 0.30) + (0.85 x 0.35) + (0.68 x 0.20) + (0.60 x 0.15)
           = 0.246 + 0.2975 + 0.136 + 0.09
           = 0.7695 (77%)
```

### Step 3: Critical Mismatch Caps

The system checks for fundamental mismatches:

```
if role_fit < 0.30:
    base_score = min(base_score, 0.35)    # Cap at 35%

if skills_fit < 0.30:
    base_score = min(base_score, 0.45)    # Cap at 45%
```

In this example, both dimensions are well above 0.30, so no cap applies.

### Step 4: Location Penalty

The deterministic location penalty is applied based on physical distance:

```
if distance <= preferred_radius:
    location_factor = 1.0
elif distance <= 2 * preferred_radius:
    location_factor = 1.0 - 0.3 * ((distance - radius) / radius)
elif remote_job:
    location_factor = 1.0
elif no_coordinates:
    location_factor = 1.0
else:
    // Job was excluded in search stage

final_score = base_score * location_factor
```

**Example with location**: If the candidate has a 50km radius and the job is 70km away:

```
location_factor = 1.0 - 0.3 * ((70 - 50) / 50) = 1.0 - 0.12 = 0.88
final_score = 0.7695 * 0.88 = 0.677 (68%)
```

### Step 5: Recommendation Assignment

Based on the final score, a recommendation is assigned:

| Final Score        | Recommendation | Meaning                                              |
| ------------------ | -------------- | ---------------------------------------------------- |
| **0.70 or higher** | **Apply**      | The AI recommends actively pursuing this opportunity |
| **0.50 to 0.69**   | **Consider**   | Worth reviewing but has notable gaps to evaluate     |
| **Below 0.50**     | **Skip**       | Significant misalignment; likely not worth pursuing  |

## Interpreting Score Ranges

<CardGroup cols={3}>
  <Card title="Excellent Match (80%+)">
    Shown in **green** in the interface. Strong alignment across all dimensions. The candidate is highly qualified for this role -- required skills are largely covered, seniority is appropriate, and experience is relevant.

    **Action**: Prioritize these for immediate outreach. You can present these to candidates with confidence. These matches typically have strong key matching points and few potential concerns.
  </Card>

  <Card title="Good Match (60-79%)">
    Shown in **yellow** in the interface. Solid alignment with some gaps. The candidate is a contender but may be missing skills, or the role might be a stretch in seniority or domain.

    **Action**: Worth discussing with the candidate. Review the key matching points and potential concerns shown on each match card. If the concerns are minor or the candidate is willing to stretch, these can be excellent placements.
  </Card>

  <Card title="Moderate Match (below 60%)">
    Shown in **red** in the interface. Partial alignment. The candidate could potentially fill this role but there are notable gaps -- either in skills, experience level, or role type.

    **Action**: Review the AI's explanation carefully. A 55% match can be perfect for a candidate looking to transition into a new area. Other times, the gaps are too significant. The key matching points and potential concerns tell you exactly where the strength and weakness lies.
  </Card>
</CardGroup>

<Warning>
  Matches below 50% are possible but rare, as the vector search pre-filters for basic relevance. If you see low-scoring matches, they typically represent edge cases where the vector similarity was high (similar keywords or embedding space) but the detailed AI evaluation found significant misalignments (wrong seniority, different domain interpretation, etc.).
</Warning>

## Using Scores Effectively

### Do Not Rely on the Number Alone

The score is a starting point, not a final answer. Always read the AI's **explanation** and review the **key matching points** (shown as green badges) and **potential concerns** (shown as orange badges) on each match card. A 75% match with minor concerns is very different from a 75% match where the concern is "5+ years of Kubernetes production experience required".

<Tip>
  Develop a habit of checking three things for every match you consider acting on: (1) the overall score, (2) the potential concerns badges, and (3) the AI explanation. This 30-second check prevents wasted outreach on matches that look good on paper but have hidden dealbreakers.
</Tip>

### Compare Within a Candidate, Not Across Candidates

Scores are relative to a specific candidate's profile. An 85% for Candidate A and an 85% for Candidate B do **not** mean those two candidates are equally qualified for the same job. The scores reflect how each candidate individually aligns with the job's requirements based on their own profile data.

If you need to compare multiple candidates for the same job, look at the specific dimension scores and key matching points rather than the overall percentage.

### Use the Recommendation Field

Each scored match includes a recommendation that provides a quick triage signal:

| Recommendation | Score Range | Best Used For                                                                                        |
| -------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
| **Apply**      | 70%+        | Immediate outreach candidates. Present to the candidate and the company.                             |
| **Consider**   | 50-69%      | Secondary pipeline. Review with the candidate to assess interest and gap tolerance.                  |
| **Skip**       | Below 50%   | Deprioritize. Only pursue if you have specific knowledge that makes this relevant despite the score. |

<Tip>
  When reviewing a large batch of new matches (50+), start by filtering to "Apply" recommendations only. Work through these first since they represent the highest-probability placements. Then move to "Consider" matches if you have time.
</Tip>

### Look at the Dimension Scores

Beyond the overall score, each match shows individual dimension scores. These tell you exactly where the strength and weakness lies:

<Tabs>
  <Tab title="Strong Technical Match">
    ```
    Overall: 78%
      Role Fit:       82%
      Skills Fit:     85%
      Experience Fit: 68%
      Secondary Fit:  60%
    ```

    This candidate is a great technical match (high skills and role fit) but might be slightly over or under-experienced. The secondary factors (education, certifications) are moderate. This is likely a good match worth pursuing -- the experience gap may close with the right framing.
  </Tab>

  <Tab title="Experience-Heavy Match">
    ```
    Overall: 74%
      Role Fit:       90%
      Skills Fit:     55%
      Experience Fit: 88%
      Secondary Fit:  82%
    ```

    This candidate has excellent role and experience alignment but a notable skills gap. They are in the right career track with great experience, but may be missing specific technologies the job requires. Check the potential concerns on the match card -- if the flagged skills are learnable frameworks or tools, this could still be an excellent placement.
  </Tab>

  <Tab title="Career Transition Match">
    ```
    Overall: 62%
      Role Fit:       45%
      Skills Fit:     78%
      Experience Fit: 55%
      Secondary Fit:  70%
    ```

    This candidate has strong skills but their role history does not directly map. This pattern is common for career changers -- someone with the right technical skills but from a different domain. Consider adjusting the candidate's scoring weights (lower role, higher skills) if this is a deliberate transition.
  </Tab>
</Tabs>

## Configuring Scoring Weights

The default weights (Role 30%, Skills 35%, Experience 20%, Secondary 15%) work well for most technical roles. However, you can customize weights per candidate to better reflect different hiring scenarios.

### When to Adjust Weights

| Scenario                                        | Suggested Adjustment                                    | Rationale                                                                    |
| ----------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Highly technical role** (ML Engineer, DevOps) | Skills: 45%, Role: 25%, Experience: 20%, Secondary: 10% | Technical skills are the primary differentiator                              |
| **Leadership role** (Engineering Manager, VP)   | Experience: 30%, Role: 30%, Skills: 25%, Secondary: 15% | Management experience and seniority matter most                              |
| **Career transition** (changing fields)         | Skills: 45%, Role: 15%, Experience: 20%, Secondary: 20% | Current role is irrelevant; transferable skills and secondary factors matter |
| **Entry-level position** (Junior Developer)     | Secondary: 25%, Role: 25%, Skills: 30%, Experience: 20% | Education and certifications differentiate junior candidates more            |
| **Regulated industry** (Banking, Healthcare)    | Secondary: 25%, Skills: 30%, Experience: 25%, Role: 20% | Certifications and compliance requirements are critical                      |
| **Freelancer/Contractor**                       | Skills: 50%, Role: 20%, Experience: 20%, Secondary: 10% | Specific technical skills are all that matters for project-based work        |

<Note>
  Weights must sum to **1.0** (100%). When you increase one weight, decrease others proportionally to maintain the balance. The system validates that all four weights sum to exactly 1.0 before saving.
</Note>

<Tip>
  **Change weights before the first match run if possible.** Adjusting weights after matching requires a re-match to recalculate all scores. If you know upfront that a candidate is a career changer or targeting leadership roles, set the weights before triggering the initial matching pipeline.
</Tip>

## What Affects Score Quality

The quality of match scores depends on the quality of input data. Understanding this helps you diagnose unexpected scores.

### Candidate Profile Quality

| Factor                        | Impact on Scores                                                         | How to Improve                                          |
| ----------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------- |
| **Confirmed skills**          | High impact -- confirmed skills are the only ones sent to the scoring AI | Always confirm skills before relying on scores          |
| **Complete CV text**          | High impact -- more context gives the AI better evidence for evaluation  | Use CV upload over LinkedIn for richer text             |
| **Accurate title**            | Medium impact -- affects Role Fit dimension and Title vector             | Edit to reflect target role, not just current/last role |
| **Correct experience level**  | Medium impact -- affects Experience Fit evaluation                       | Verify auto-calculated level is appropriate             |
| **Location with coordinates** | Impact on final score only -- location penalty is applied post-scoring   | Ensure geocoded location is set                         |

### Job Listing Quality

| Factor                            | Impact on Scores                                         | What Happens When Missing                                 |
| --------------------------------- | -------------------------------------------------------- | --------------------------------------------------------- |
| **Detailed job description**      | High impact -- the AI needs content to evaluate against  | Vague descriptions produce middle-of-the-road scores      |
| **Clear skill requirements**      | High impact on Skills Fit dimension                      | Without explicit requirements, the AI infers from context |
| **Salary information**            | No impact on scoring (used for candidate filtering only) | N/A                                                       |
| **Job location with coordinates** | Impact on location penalty calculation                   | No location penalty applied (factor = 1.0)                |
| **Company information**           | Minor impact on Secondary Fit                            | Jobs without company data are filtered out in search      |

<Info>
  Jobs with very short or missing descriptions receive scores that tend toward the middle range (50-65%) because the AI does not have enough information to confidently rate the match in either direction. If you notice many moderate-scoring matches with brief descriptions, this is expected behavior -- the AI is being appropriately uncertain.
</Info>

### Location Data

| Scenario                      | Location Factor | Score Impact                                     |
| ----------------------------- | --------------- | ------------------------------------------------ |
| Both geocoded, within radius  | 1.0             | No impact                                        |
| Both geocoded, at 1.5x radius | \~0.85          | \~15% reduction                                  |
| Both geocoded, at 2x radius   | 0.70            | 30% reduction                                    |
| Missing candidate coordinates | 1.0             | No penalty (may inflate scores for distant jobs) |
| Missing job coordinates       | 1.0             | No penalty                                       |
| Remote job                    | 1.0             | No penalty regardless of distance                |

<Tip>
  If you notice that a candidate's match scores seem consistently off, check these three things in order:

  1. **Skills list** -- Are the confirmed skills accurate and complete? This is the most common cause of poor match quality.
  2. **Title** -- Does the title accurately represent the candidate's target role? A generic title like "Consultant" produces very different matches than "Senior Python Developer".
  3. **Experience level** -- Is the level appropriate? A "Junior" classification for a senior candidate will penalize senior-level job matches.
</Tip>

## Advanced

### The Scoring Prompt Engineering

The AI scoring uses a carefully engineered prompt (CANDIDATE\_JOB\_SCORING\_PROMPT) that instructs Gemini to produce consistent, calibrated scores. Key aspects of the prompt design:

* **Calibration instructions**: The AI is told to use the full 0-1 range and not cluster scores around 0.5. This ensures meaningful differentiation between good and great matches.
* **Evidence requirement**: The AI must provide specific evidence from both the CV text and job description to justify each dimension score. This prevents hallucinated evaluations.
* **Independent evaluation**: Each dimension is evaluated separately before being combined. This prevents halo effects where a strong skill match biases the experience evaluation.
* **Structured output**: The response is a JSON object with scores, skill lists, explanation, and recommendation. This enables reliable parsing and display.

### How the Critical Penalty Caps Work

The caps at role\_fit \< 0.30 and skills\_fit \< 0.30 are applied as post-processing after the weighted combination. They are independent checks:

```python theme={null}
final_score = weighted_combination(role_fit, skills_fit, experience_fit, secondary_fit)

if role_fit < 0.30:
    final_score = min(final_score, 0.35)

if skills_fit < 0.30:
    final_score = min(final_score, 0.45)
```

Note that both caps can apply simultaneously. If a candidate has both role\_fit \< 0.30 AND skills\_fit \< 0.30, the score is capped at min(0.35, 0.45) = **0.35**.

The cap values (0.35 and 0.45) were chosen based on the principle that:

* A fundamental role mismatch is the most severe issue (lower cap at 0.35)
* A fundamental skills gap is serious but slightly more recoverable (higher cap at 0.45)

### Score Distribution Patterns

In practice, you will observe characteristic score distributions based on candidate profile quality:

**Well-configured candidate** (confirmed skills, accurate title, proper location): Most scores between 60-90%, clear differentiation between good and mediocre matches.

**Partially configured candidate** (unconfirmed skills, generic title): Scores tend to cluster around 55-70%, with less differentiation. The AI lacks the specific signals to confidently rate matches.

**Overly broad skill list** (30+ skills confirmed): Scores tend to be inflated because the candidate appears to match many jobs. The Skills vector becomes too broad, losing specificity.

**Overly narrow skill list** (3-4 skills): Fewer matches overall, but the matches that do appear tend to be highly relevant with high scores.

### How Location Penalty Interacts with Dimension Scores

The location penalty is applied **after** the weighted combination and cap checks. This means:

1. A job can have excellent dimension scores (85% base) but a poor final score (60%) due to distance
2. A nearby job with moderate dimension scores (70% base) can outrank a distant job with better dimension scores (85% base, 60% after location penalty)
3. Remote jobs are never penalized, giving them an inherent advantage over on-site jobs at the margin of the radius

This is intentional -- a geographically convenient match is genuinely more valuable than a slightly better-scoring match that requires an impractical commute.

### Power-User Tips

<Tip>
  **Look for patterns across matches, not just individual scores.** If a candidate consistently scores high on Skills Fit but low on Role Fit across many matches, it suggests their title or career narrative does not align with the roles they are being matched to. Consider editing the title or adjusting the role weight downward.
</Tip>

<Tip>
  **The potential concerns are your coaching tool.** When a candidate has a 75% match with a concern about a missing skill (e.g., "Kubernetes experience not evident"), this gives you a concrete development recommendation. If the skill is learnable and the candidate is motivated, this insight adds value to your recruiter-candidate relationship.
</Tip>

<Tip>
  **Recalibrate your expectations for different markets.** In a tight labor market with high demand for specific skills, even a 65% match might represent a viable placement. In a loose market with many available candidates, you might focus exclusively on 80%+ matches. Let market conditions guide how you interpret the score ranges.
</Tip>

<Tip>
  **Use dimension breakdowns when presenting to clients.** Instead of saying "this candidate is an 82% match", say "this candidate scores 90% on skills fit with Python, FastAPI, and PostgreSQL all covered, and 75% on experience fit with 5 years in backend development." The dimension breakdown is more convincing and actionable than a single number.
</Tip>

## Related

* [Candidate Pipeline](/candidates/matching/candidate-pipeline) -- Organize matches into your workflow based on scores
* [How Matching Works](/candidates/matching/how-matching-works) -- Deeper dive into the matching technology that produces these scores
* [Skills & Expertise](/candidates/skills-and-expertise) -- Improve scores through better skill data
* [Location & Preferences](/candidates/location-and-preferences) -- Understand how location affects final scores