Fix poor search quality from Hermes-based agents by checking five common failure points: model size affecting query construction, tool configuration errors, suboptimal query phrasing, search provider quality, and prompt template issues. Hermes 3 is a capable tool-use model, but its search quality depends heavily on how the search tool is configured and what search backend it calls. Most quality issues trace back to the model generating overly broad queries or the search provider returning low-relevance results.
Prerequisites
- A running Hermes agent with search capability
- Python 3.8+ installed
- requests library installed
- A Scavio API key from scavio.dev for comparison
Walkthrough
Step 1: Check model size impact
Verify which Hermes model variant you are running. Smaller models construct worse search queries.
Python
import requests, os, json
SCAVIO_KEY = os.environ['SCAVIO_API_KEY']
OLLAMA_URL = 'http://localhost:11434'
def check_model():
try:
resp = requests.get(f'{OLLAMA_URL}/api/tags', timeout=5)
models = resp.json().get('models', [])
hermes_models = [m for m in models if 'hermes' in m.get('name', '').lower()]
for m in hermes_models:
size = m.get('size', 0) / (1024**3)
print(f"{m['name']}: {size:.1f}GB")
if size < 4:
print(' WARNING: Small model may construct poor queries')
print(' Recommendation: Use hermes3:8b or larger')
if not hermes_models:
print('No Hermes models found in Ollama')
return hermes_models
except Exception as e:
print(f'Cannot connect to Ollama: {e}')
return []
check_model()Step 2: Verify tool configuration
Check that the search tool definition gives Hermes enough context to construct good queries.
Python
GOOD_TOOL_DEF = {
'type': 'function',
'function': {
'name': 'web_search',
'description': 'Search the web for current information. Use specific, focused queries. Include the year 2026 for time-sensitive topics.',
'parameters': {
'type': 'object',
'properties': {
'query': {
'type': 'string',
'description': 'The search query. Be specific: include product names, versions, dates. Bad: "best tools". Good: "best CRM for startups 2026".',
},
},
'required': ['query'],
},
},
}
BAD_TOOL_DEF = {
'type': 'function',
'function': {
'name': 'search',
'description': 'Search',
'parameters': {'type': 'object', 'properties': {'q': {'type': 'string'}}},
},
}
print('GOOD: Descriptive name, detailed description, query guidance')
print('BAD: Vague name, no description, no query guidance')
print('Fix: Use the GOOD tool definition pattern above')Step 3: Test query construction quality
Send a user prompt to Hermes and inspect what search query it generates. Compare bad vs good queries.
Python
def test_query_quality(user_prompt: str) -> dict:
"""Test what query Hermes would construct for a given prompt."""
# Simulate Hermes query construction
# In practice, inspect your agent's tool call logs
example_bad_queries = {
'What CRM should I use?': 'CRM', # Too broad
'Compare React and Vue': 'react vue', # Missing context
'Latest Python release': 'python release', # Missing year
}
example_good_queries = {
'What CRM should I use?': 'best CRM for small business 2026 comparison',
'Compare React and Vue': 'React vs Vue performance comparison 2026',
'Latest Python release': 'Python latest version release date 2026',
}
bad = example_bad_queries.get(user_prompt, user_prompt)
good = example_good_queries.get(user_prompt, user_prompt)
# Compare result quality
bad_results = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': SCAVIO_KEY},
json={'platform': 'google', 'query': bad}, timeout=10).json().get('organic_results', [])
good_results = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': SCAVIO_KEY},
json={'platform': 'google', 'query': good}, timeout=10).json().get('organic_results', [])
print(f'Bad query "{bad}": {len(bad_results)} results')
print(f'Good query "{good}": {len(good_results)} results')
return {'bad_query': bad, 'good_query': good}
test_query_quality('What CRM should I use?')Step 4: Compare search providers
Test the same query across different providers to determine if the issue is the search backend or the query.
Python
def compare_providers(query: str) -> dict:
# Test with Scavio (structured API)
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': SCAVIO_KEY},
json={'platform': 'google', 'query': query}, timeout=10)
scavio_results = resp.json().get('organic_results', [])
# Test with SearXNG (if running locally)
searxng_results = []
try:
resp = requests.get('http://localhost:8080/search',
params={'q': query, 'format': 'json'}, timeout=10)
searxng_results = resp.json().get('results', [])
except:
pass
print(f'Query: {query}')
print(f'Scavio: {len(scavio_results)} results')
if scavio_results:
print(f' Top: {scavio_results[0].get("title", "")[:60]}')
print(f'SearXNG: {len(searxng_results)} results')
if searxng_results:
print(f' Top: {searxng_results[0].get("title", "")[:60]}')
return {'scavio': len(scavio_results), 'searxng': len(searxng_results)}
compare_providers('best CRM for startups 2026')Step 5: Optimize prompts for better queries
Update the system prompt to guide Hermes toward constructing better search queries.
Python
OPTIMIZED_SYSTEM_PROMPT = """You are a research assistant with web search capability.
When using the web_search tool:
1. Always include specific terms (product names, versions, years)
2. Add "2026" for time-sensitive topics
3. Use comparison terms when the user asks for recommendations
4. Break complex questions into multiple focused searches
5. Prefer "best X for Y" over just "X"
Examples:
- User: "What CRM should I use?" -> search: "best CRM for small business comparison 2026"
- User: "Is React still good?" -> search: "React framework popularity and performance 2026"
"""
def build_hermes_prompt(user_message: str) -> str:
return f"{OPTIMIZED_SYSTEM_PROMPT}\n\nUser: {user_message}"
print(build_hermes_prompt('What project management tool should I use?'))
print('\nThis prompt guides Hermes to construct specific, high-quality search queries.')Python Example
Python
import requests, os
H = {'x-api-key': os.environ['SCAVIO_API_KEY']}
def quality_check(broad_query, specific_query):
broad = requests.post('https://api.scavio.dev/api/v1/search', headers=H,
json={'platform': 'google', 'query': broad_query}).json()
specific = requests.post('https://api.scavio.dev/api/v1/search', headers=H,
json={'platform': 'google', 'query': specific_query}).json()
print(f'Broad "{broad_query}": {len(broad.get("organic_results", []))} results')
print(f'Specific "{specific_query}": {len(specific.get("organic_results", []))} results')
quality_check('CRM', 'best CRM for startups 2026')JavaScript Example
JavaScript
const H = {'x-api-key': process.env.SCAVIO_API_KEY, 'Content-Type': 'application/json'};
async function qualityCheck(broad, specific) {
const r1 = await fetch('https://api.scavio.dev/api/v1/search', {
method: 'POST', headers: H, body: JSON.stringify({platform: 'google', query: broad})
});
const r2 = await fetch('https://api.scavio.dev/api/v1/search', {
method: 'POST', headers: H, body: JSON.stringify({platform: 'google', query: specific})
});
console.log(`Broad: ${((await r1.json()).organic_results || []).length} results`);
console.log(`Specific: ${((await r2.json()).organic_results || []).length} results`);
}
qualityCheck('CRM', 'best CRM for startups 2026');Expected Output
JSON
A diagnostic checklist that identifies and fixes Hermes search quality issues through model size checks, tool config improvements, query optimization, and provider comparison.