Freshservice KB Relevance Scoring: Tuning the Self-Service Engine

A user types “vpn not connecting” into the self-service portal. The top result is a 2024 article called “Configuring SSL VPN on legacy clients”. The actual current article — “Connecting to the corporate VPN with Cisco AnyConnect 2026” — is buried at position five. The user gives up and opens a ticket. This happens thousands of times per quarter at any organisation past a few hundred employees, and the fix is in search relevance tuning, not more articles.

What the scoring engine considers

Freshservice’s KB search blends several signals to rank articles. The ones you can influence:

• Term frequency in title and body — exact matches in the title score highest.
• Article freshness — recently updated articles get a small boost.
• View count and helpful votes — popular articles surface higher.
• Category and folder weighting — articles in matched categories rank above those in unrelated ones.
• Explicit boosts — admin-applied weight to specific articles.
• Synonym dictionaries — terms mapped to canonical equivalents.

The signals you cannot directly tune (precise vector embedding weights, learning-to-rank coefficients) matter less than the ones you can. Most ranking failures come from neglected synonyms and missing freshness signals.

The freshness problem

KB articles age. The 2024 SSL VPN article got 12,000 views when it was current. Those views still count toward its rank today, three years later, even though the content is obsolete. The newer article has 600 views because nobody can find it.

Two fixes:

1. Archive aggressively. Anything that has not been edited or visited in 18 months should be a candidate for archival. Run quarterly.
2. Apply a freshness decay. If the platform’s native decay is too weak, manually penalise old articles by editing them with a [Legacy] prefix in the title or by moving them to an archive folder excluded from default search.

curl -s -u "$FS_KEY:X" \
  "https://acme.freshservice.com/api/v2/solutions/articles?per_page=100" \
  | jq '[.articles[] | select(.updated_at < "2024-11-14")
         | {id, title, views, updated_at, status}]
        | sort_by(.views) | reverse'

Sort old articles by views descending. Anything with thousands of views that has not been touched in 18 months is either still useful (update it) or actively harmful (archive it). Pick one.

Synonyms: the highest-leverage edit

The single most underused tuning lever is the synonym dictionary. Users do not use your internal terminology. They type the symptom in their own words.

Examples worth adding to most synonym dictionaries:

laptop = computer = workstation = device
locked out = can't login = password reset = forgot password
wifi = wireless = wi-fi = wlan
slow = lagging = freezing = unresponsive
vpn = remote access = secure access = anyconnect
office = m365 = microsoft 365 = office 365

Add 30-40 mappings tuned to your environment. Search relevance improves overnight. The work is to mine the search logs for failed queries (queries that returned no useful clicks) and see what users typed. Each failed query is a candidate for a synonym, a missing article, or both.

Mining search logs

curl -s -u "$FS_KEY:X" \
  "https://acme.freshservice.com/api/v2/solutions/search_logs?since=2026-04-14" \
  | jq '[.queries[] | select(.clicked == false)
         | {query, count, last_seen}]
        | group_by(.query)
        | map({query: .[0].query, count: ([.[].count] | add)})
        | sort_by(.count) | reverse | .[0:50]'

The top 50 unclicked queries are your tuning to-do list. For each:

• Does an article actually exist for this? If not, write one.
• Does an article exist but rank too low? Boost or add to synonym dictionary.
• Is the article there but the title does not match user vocabulary? Rename the article.

Renaming articles to user-facing vocabulary is the highest-leverage fix, full stop. Internal teams write titles like “Active Directory password reset procedure”; users type “forgot my password”. Rename to “Forgot your password? Reset it here” and keep the AD specifics in the body.

Boosts and demotions

Explicit boosts are admin-applied weighting. Use sparingly. Two valid uses:

• Compliance-critical articles — security policy, acceptable use policy. Always surface for relevant queries.
• Just-deployed change communications — for the first 30 days after a major change, boost the change-summary article so the queries it answers find it first.

Demotions are the inverse. The legacy article you cannot fully retire — keep it for historical reference, demote it so the new article ranks above it.

{
  "article_id": 5012,
  "title": "Configuring SSL VPN on legacy clients",
  "boost": -0.5,
  "include_in_default_search": false,
  "categories": ["archive_legacy"]
}

Document every boost and demotion in an “overrides” file. Six months later, when search results look weird, the file is the first stop.

Category and folder structure

If your KB has 30 folders all named with department-internal acronyms, search is fighting you. Categories influence ranking; bad categories produce noise.

Three rules:

• Folder names should be user-facing. “Login & Access”, not “IAM-T1”.
• Articles live in the folder that matches the user’s mental model, not the team that wrote them.
• Maximum two levels of folder depth. Deeper hierarchies are search-hostile and rarely browsed.

See freshdesk-solutions-kb-governance for the broader governance pattern on KB structure.

Helpful-vote signals

The thumbs-up/thumbs-down on the bottom of each article is a useful signal if you read it. Articles with high negative ratio should be auto-flagged for review. Articles with high positive ratio for the query that found them should be slight boost candidates.

Build a weekly digest:

• Articles with helpful-rate under 30% — flag for editorial review.
• Articles with helpful-rate over 80% and view count rising — consider boosting and linking from related articles.
• Articles with rising no-vote rate — readers are not engaging at all, possibly because the article does not match the query intent.

Deflection as the actual metric

Tuning relevance is means; deflection is the end. The metric:

Deflection rate = (resolved by self-service) / (resolved by self-service + tickets opened)

Measure quarterly. Segment by topic area. A category where deflection is dropping is a category where tuning, fresh content, or both are needed.

The trap is measuring search satisfaction in isolation. A search where the user found an article and clicked it is not a successful deflection if the user came back twenty minutes later and opened a ticket because the article did not actually solve their problem. Track the second-touch behaviour.

Connecting to Freddy

If you have Freddy self-service tuning enabled, the KB feeds Freddy’s answer-generation. Garbage KB content produces confidently-stated garbage answers. The synonym work, the archival, the renaming — they all feed Freddy’s quality.

See freddy-copilot-self-service-tuning for the Freddy-side tuning that pairs with KB tuning.

A quarterly tuning ritual

Block four hours per quarter. Agenda:

• Pull top 50 failed queries. Fix at least 20.
• Pull articles updated more than 18 months ago, sorted by views. Archive or refresh the top 30.
• Review the synonym dictionary; add 5-10 new mappings.
• Audit the overrides file; remove any that are no longer needed.
• Pull deflection rate by category; pick the worst category for next quarter’s focus.

Four hours, every quarter. The compounding effect on deflection is real and substantial.

Bottom line

KB relevance tuning is mostly synonym work and aggressive archival. Mine the failed queries, write articles in user vocabulary, prune the legacy long tail, and use explicit boosts only when justified. Measure deflection, not search clicks. The KB that deflects 60% of demand and the one that deflects 25% have the same article count — they differ in whether someone spent four hours per quarter on the tuning ritual.