Skip to main content

Best Practices

This guide covers best practices for using HG MCP Server tools effectively and efficiently.

Check the tool reference for the full schema

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-After of 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 CodeMeaningSolution
MISSING_INTEGRATIONRequired integration not configuredConfigure integration in settings
INVALID_PARAMETERSParameters don't match schemaCheck parameter types and requirements
RATE_LIMIT_EXCEEDEDToo many requestsImplement backoff, reduce request rate
COMPANY_NOT_FOUNDCompany doesn't exist in databaseVerify domain is correct
INTERNAL_ERRORServer errorRetry 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);
}

Next Steps​