HG Credit Awareness

Keep a workflow inside the org's credit budget without losing the data it needs.

When to use

• Planning a workflow that loops over an account list or a territory.
• Choosing between company_enrich and the dedicated batch tools.
• A call has a cost-changing option (revealPhone, searchDepth, max_results, depth, full).
• The user asks to "refresh" data or re-run a workflow.

Credit table

Batch tools bill proportionally: rate × companies in the batch (up to 25 per call).

Tool	Credits
company_firmographic	0.1 per company
company_technographic	2 per company
company_spend	3 per company
company_ai_spend	2 per company
company_ai_maturity	2 per company
company_contracts	1 per company
company_enrich	Sum of requested sections per matched company (firmographics 0.1, technographics 2, spend 3, ai_spend 2, ai_maturity 2, contracts 1); default 3 sections = 5.1
company_fai	2 per call
company_intent	0.1 per call
company_operating_signals	2 per call
company_cloud_spend	2 per call
company_install_time_series	3 per product row returned (one row per product per country with granularity:"country"); 0 if empty
company_hierarchy	0.1 per node returned
search_companies	1 per 100 companies returned
contact_search	2 per call
contact_enrich	0.2 per email reveal + 2 per phone reveal, per matched contact
product_search_and_enrich	Search free; enrich 1 per matched product
get_product_category, get_product_attribute, get_vendor_information, list_intent_topics, list_fai_departments, search_industries_naics_sic, hg_catalog, phoenix_*	Free
SEC tools and gov tools	1 per call
web_search	0.05 basic, 0.10 advanced
hg_data_query	Depends on data scanned, reported in credits_consumed (can be non-zero with 0 rows)
phoenix_invoke_agent, market_data_agent	Metered separately, billed through the run

Each response reports what it actually billed; a cached call reports 0.

Cache rules

• Company tools cache for 30 days (intent included), reviews for 14 days, search and contact tools for 7 days, the catalog for 1 day. The cache is org-wide: if a colleague made the same call, yours costs 0.
• A no-coverage answer caches for 6 hours.
• There is no way to force a refresh inside the window. A re-call returns the cached payload. Don't schedule "weekly refreshes" of firmographic or technographic data, and don't promise the user fresher data than the cache allows.
• Each batch is its own cache entry: the same company inside a different batch isn't a cache hit. Reuse the same batches when re-running a workflow.
• Never cached, billed on every call: company_ai_maturity, SEC tools, gov tools, web_search, and the per-result tools (time series, hierarchy, product enrich, hg_data_query). Don't re-call these "to refresh".

Enforcement

Trial orgs run under hard enforcement: a call is refused when its cost would take the org past its limit, so the expensive tools stop first while free lookups and cached answers keep working. Other orgs may differ. If you see a credit-limit error, stop and tell the user; retrying won't help.

Decision rules

Resolve for free first. Product, category, topic, department and industry ids come from free lookups. A paid call on a guessed id returns nothing useful.

Pre-filter cheap, enrich late. For a territory:

1. search_companies with two or more filter groups (e.g. 300 companies = 3 credits).
2. company_firmographic on the survivors (300 × 0.1 = 30).
3. company_technographic with product_ids on the top 50 (100).
4. company_intent with resolved topic_ids on the top 20 (2).
5. FAI, contacts and spend only for the 10 accounts the workflow will act on.

Batch with the dedicated tools. For one or two sections across many companies, call the batch tools (25 per call) with filters. Use company_enrich only when you need several sections for a few companies: the per-company cost is the same, but enrich caps each section and gives fewer filtering options.

Name every cost-changing option explicitly. Don't rely on defaults:

Option	Default	Pass
contact_enrich revealPhone	true (2 credits per matched contact, charged even when no phone comes back)	revealPhone:false unless a phone is needed
company_install_time_series max_results	10 products = up to 30 credits	product_ids for the products you care about
company_install_time_series granularity:"country"	off	Leave off unless you need countries (multiplies rows)
company_hierarchy depth	1	mode:"parents" for ownership; large groups return 100 to 330+ nodes (10 to 33 credits)
web_search searchDepth	basic	Name it; use "advanced" only when relevance matters
company_enrich fields	3 sections (5.1 per company)	Only the sections you need

Count retries. A failed call isn't charged, but every successful re-call of an uncached tool is. An LLM that loops on web_search, SEC or company_ai_maturity burns credits on each pass.

Reuse within a run. If the workflow already loaded a company's firmographic record, read from it instead of calling again.

Common pitfalls

1. Leaving revealPhone at its default on a contact list.
2. Calling company_install_time_series without product_ids.
3. Running company_enrich with default fields on a 25-company list when only one section is needed.
4. Promising a "fresh pull" inside the cache window.
5. Re-running uncached tools to "double-check".

Reference

• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/overview
• Full docs for LLMs: https://phoenix.hginsights.com/docs/llms-full.txt
• Related skills: hg-mcp-calling-rules, hg-tool-chain-account-research, hg-fai-vs-contact-search