Best Practices
This guide covers best practices for using HG MCP Server tools effectively and efficiently.
The payloads and response paths below match the tools as served today: company tools take batch
arrays (domains, hg_ids) and return { companies: [...] } with snake_case rows. Only the
fields each example needs are shown — see the tool's own
reference page for the complete parameter and response schema.
Rate Limiting
Understanding Limits
HG Insights enforces a per-minute limit on tool calls, shared across your whole organization:
- 1,000 tool calls per minute per organization. All of your organization's API keys draw on the same window — the limit is per company, not per key, so adding keys does not raise your ceiling. Discovery/protocol traffic (
initialize,tools/list, etc.) is tracked separately and rarely a constraint. - 20 tool calls per second per organization. A burst cap on top of the per-minute one — a clump of calls in a single second is rejected even when you are well inside your minute budget, with a
Retry-Afterof about a second. Pace bulk work instead of firing it all at once. - Cache hits still count toward both limits. They cost zero credits, but they do not buy extra throughput. See Caching & Pricing.
Best Practices
1. Batch Your Requests
Instead of making sequential calls, batch independent requests:
❌ Bad - one call per company:
const companies = ['example1.com', 'example2.com', 'example3.com'];
for (const domain of companies) {
const result = await mcp.call('company_firmographic', { domains: [domain] });
console.log(result.companies[0]);
}
// Three calls against your rate limit, and three round-trips
✅ Good - one batch call:
const companies = ['example1.com', 'example2.com', 'example3.com'];
// Company tools take a batch of up to 25 domains per call.
const { companies: rows } = await mcp.call('company_firmographic', {
domains: companies
});
// One call, one round-trip. Rows come back keyed by `company_domain`.
const byDomain = new Map(rows.map(r => [r.company_domain, r.firmographics]));
2. Implement Exponential Backoff
When you hit rate limits, use exponential backoff:
async function callWithRetry(tool, params, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await mcp.call(tool, params);
} catch (error) {
if (error.code === 'RATE_LIMIT_EXCEEDED' && i < maxRetries - 1) {
const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
await new Promise(resolve => setTimeout(resolve, delay));
continue;
}
throw error;
}
}
}
3. Use Company Search Wisely
search_companies can return hundreds of results. Limit results to what you need:
Filters nest under firmographics.
❌ Bad — a broad filter with a large limit burns quota on rows you will not read:
{
"tool": "search_companies",
"parameters": {
"firmographics": { "industries": [{ "ids": [7], "inclusion_method": "ANY_PRESENT" }] },
"limit": 500
}
}
✅ Good — narrow the filters and keep limit to what you will actually use:
{
"tool": "search_companies",
"parameters": {
"firmographics": {
"industries": [{ "ids": [7], "inclusion_method": "ANY_PRESENT" }],
"employees": { "min": 1000, "max": 5000 }
},
"limit": 50
}
}
Resolve industry IDs with search_industries_naics_sic rather than guessing. limit caps at 100.
Caching Strategy
Understanding HG Insights Caching
HG Insights caches many tool responses, and a cache hit costs zero credits. Durations run much longer than most people assume — 30 days for most company data tools, 14 days for product reviews, 7 days for searches and contact lookups, 1 day for the catalog. Not every tool is cached, though: see Caching & Pricing for the complete per-tool table and the list of uncached tools.
The cache is org-scoped: every user and every API key in your organization shares one bucket, so the first caller pays and everyone after them reads for free until it expires.
Cache hits do still consume rate-limit budget. They cost no credits, but they do not buy extra throughput.
Best Practices
1. Implement Client-Side Caching
Add your own caching layer for frequently accessed data:
const cache = new Map();
const CACHE_TTL = 60 * 60 * 1000; // 1 hour
async function getCachedCompanyData(domain) {
const cacheKey = `firmographic:${domain}`;
const cached = cache.get(cacheKey);
if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
return cached.data;
}
const { companies } = await mcp.call('company_firmographic', {
domains: [domain]
});
const data = companies[0]?.firmographics ?? null;
cache.set(cacheKey, { data, timestamp: Date.now() });
return data;
}
2. Avoid Redundant Calls
Track what you've already fetched:
const fetchedCompanies = new Set();
async function fetchIfNeeded(domain) {
if (fetchedCompanies.has(domain)) {
console.log(`Already fetched ${domain}, skipping`);
return null;
}
fetchedCompanies.add(domain);
return await mcp.call('company_firmographic', { domains: [domain] });
}
Error Handling
Common Errors
| Error Code | Meaning | Solution |
|---|---|---|
MISSING_INTEGRATION | Required integration not configured | Configure integration in settings |
INVALID_PARAMETERS | Parameters don't match schema | Check parameter types and requirements |
RATE_LIMIT_EXCEEDED | Too many requests | Implement backoff, reduce request rate |
COMPANY_NOT_FOUND | Company doesn't exist in database | Verify domain is correct |
INTERNAL_ERROR | Server error | Retry once, then contact support |
Robust Error Handling
async function robustToolCall(tool, params) {
try {
return await mcp.call(tool, params);
} catch (error) {
// Log error details
console.error(`Tool ${tool} failed:`, {
code: error.code,
message: error.message,
params: params
});
// Handle specific errors
switch (error.code) {
case 'COMPANY_NOT_FOUND':
return { notFound: true, domains: params.domains };
case 'RATE_LIMIT_EXCEEDED':
// Wait and retry
await new Promise(r => setTimeout(r, 5000));
return await mcp.call(tool, params);
case 'MISSING_INTEGRATION':
throw new Error(
`Required integration missing. Please configure: ${error.requiredIntegrations.join(', ')}`
);
default:
// Re-throw unknown errors
throw error;
}
}
}
Tool Composition
Effective Tool Chaining
Chain tools logically from broad to specific:
Research Workflow Pattern
1. search_companies (broad discovery)
↓
2. company_firmographic (basic validation)
↓
3. company_technographic (tech fit check)
↓
4. company_intent (timing check)
↓
5. company_spend (budget validation)
Implementation
async function qualifyCompany(domain) {
// Step 1: Basic info
const firmoResult = await mcp.call('company_firmographic', {
domains: [domain]
});
const firmographics = firmoResult.companies[0]?.firmographics;
// Early exit if company too small
if ((firmographics?.employees_total ?? 0) < 100) {
return { qualified: false, reason: 'Too small' };
}
// Step 2: Technology fit
const techResult = await mcp.call('company_technographic', {
domains: [domain],
product_names: ['Salesforce']
});
const installs = techResult.companies[0]?.installs ?? [];
if (installs.length === 0) {
return { qualified: false, reason: 'No target technology' };
}
// Step 3: Buying signals — company_intent is single-company and returns a
// flat envelope, not a `companies` array.
const intent = await mcp.call('company_intent', {
company_domain: domain,
fields: ['summary', 'topics']
});
const topScore = Math.max(
0,
...(intent.topics?.data ?? []).map(t => t.score ?? 0)
);
if (topScore > 70) {
return {
qualified: true,
score: topScore,
firmographics,
installs
};
}
return { qualified: false, reason: 'Low intent' };
}
Parallel Processing
When data isn't dependent, fetch in parallel:
async function getCompleteProfile(domain) {
// These calls don't depend on each other
const [firmographic, technographic, intent, spending] = await Promise.all([
mcp.call('company_firmographic', { domains: [domain] }),
mcp.call('company_technographic', { domains: [domain] }),
mcp.call('company_intent', { company_domain: domain }),
mcp.call('company_spend', { domains: [domain] })
]);
return {
firmographics: firmographic.companies[0]?.firmographics ?? null,
installs: technographic.companies[0]?.installs ?? [],
intent: intent.data_available ? intent.summary : null,
spend: spending.companies[0]?.spend?.all ?? []
};
}
Data Quality
Validating Results
Always validate data before using it:
function validateFirmographic(firmographics) {
if (!firmographics) {
console.warn('No firmographics row returned for this domain');
return false;
}
const required = ['name', 'domain', 'employees_total'];
const missing = required.filter(field => !firmographics[field]);
if (missing.length > 0) {
console.warn(`Missing fields: ${missing.join(', ')}`);
return false;
}
// Validate ranges
if (firmographics.employees_total < 0) {
console.warn('Invalid employee count');
return false;
}
return true;
}
const result = await mcp.call('company_firmographic', {
domains: ['example.com']
});
const firmographics = result.companies[0]?.firmographics;
if (validateFirmographic(firmographics)) {
// Use the data
processCompany(firmographics);
} else {
// Handle invalid data
logDataQualityIssue(result);
}
Handling Missing Data
Not all companies have complete data. Handle missing fields gracefully:
function safelyAccessData(firmographics) {
return {
name: firmographics.name || 'Unknown',
employees: firmographics.employees_total || 'Not available',
revenue: firmographics.revenue_band || 'Not disclosed',
industry: firmographics.industry_name || 'Unknown',
location: firmographics.city_name
? `${firmographics.city_name}, ${firmographics.state_name}`
: 'Location not available'
};
}
Performance Optimization
1. Request Only What You Need
Use specific filters to reduce data transfer:
❌ Bad:
const all = await mcp.call('company_technographic', {
domains: ['example.com']
});
// Pays for and transfers every install, then throws almost all of them away
const salesforceOnly = (all.companies[0]?.installs ?? []).filter(
i => i.product_name === 'Salesforce'
);
✅ Good:
// Resolve a category id first, then let the server do the filtering
const { categories } = await mcp.call('get_product_category', {
categoryName: 'CRM'
});
const crmCategoryId = categories[0]?.category_id;
const tech = await mcp.call('company_technographic', {
domains: ['example.com'],
category_ids: [crmCategoryId]
});
const installs = tech.companies[0]?.installs ?? [];
2. Monitor Performance
Track tool execution times:
async function timedCall(tool, params) {
const start = Date.now();
try {
const result = await mcp.call(tool, params);
const duration = Date.now() - start;
console.log(`${tool} completed in ${duration}ms`);
// Alert on slow calls
if (duration > 5000) {
console.warn(`Slow call detected: ${tool} took ${duration}ms`);
}
return result;
} catch (error) {
const duration = Date.now() - start;
console.error(`${tool} failed after ${duration}ms`);
throw error;
}
}
3. Use Streaming for Large Datasets
For large result sets, process results as they arrive:
// Paginate on total_count — there is no `hasMore` flag in the response.
async function* streamCompanySearch(filters) {
const BATCH_SIZE = 50;
let offset = 0;
for (;;) {
const result = await mcp.call('search_companies', {
...filters,
limit: BATCH_SIZE,
offset
});
const companies = result.companies ?? [];
for (const company of companies) {
yield company;
}
offset += companies.length;
if (companies.length === 0 || offset >= result.total_count) break;
}
}
// Usage — filters nest under `firmographics`; industry ids come from
// search_industries_naics_sic, not a free-text name
for await (const company of streamCompanySearch({
firmographics: { industries: [{ ids: [7], inclusion_method: 'ANY_PRESENT' }] }
})) {
await processCompany(company);
}
Security
1. Protect API Keys
Never expose API keys in client-side code:
❌ Bad:
// Client-side code
const apiKey = 'pk_live_abc123'; // Exposed in browser!
✅ Good:
// Server-side only
const apiKey = process.env.PHOENIX_API_KEY;
// Client calls your backend
fetch('/api/company-data', {
method: 'POST',
body: JSON.stringify({ domain: 'example.com' })
});
2. Validate User Input
Always validate domains and parameters from users:
function isValidDomain(domain) {
// Basic validation
const domainRegex = /^[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,}$/i;
return domainRegex.test(domain);
}
async function safeCompanyLookup(userInput) {
const domain = userInput.trim().toLowerCase();
if (!isValidDomain(domain)) {
throw new Error('Invalid domain format');
}
return await mcp.call('company_firmographic', {
domains: [domain]
});
}
3. Implement Usage Limits
Add application-level rate limiting:
const userLimits = new Map();
async function rateLimitedCall(userId, tool, params) {
const key = `${userId}:${Date.now() / 1000 / 60 | 0}`; // Per minute
const count = userLimits.get(key) || 0;
if (count >= 10) { // 10 requests per minute per user
throw new Error('User rate limit exceeded');
}
userLimits.set(key, count + 1);
return await mcp.call(tool, params);
}