HG Workflow Authoring

How to write an HG workflow: a .md system prompt that chains HG MCP tools into a business output and gives the same answer every time it runs on the same inputs.

When to use

• Building a new workflow for a GTM use case (account brief, churn score, competitive takeout, territory plan).
• Adapting a GTM Marketplace workflow to a customer's own portfolio, competitors or format.
• Reviewing a workflow that gives different answers on repeat runs, overspends, or makes claims nothing traces to.

What a workflow is

A workflow is a plain-text .md file holding the entire system prompt for one task. When it runs, the LLM asks the user for the inputs it needs, calls the tools, and returns the output. Build the file in one LLM session and run it in a fresh one. Always save the file, even for a one-off: the request to rerun it, on another account or for another team, always comes. The file is the asset; each brief is one run of it.

Structure it as separate files

File	Holds
Data-pull file	Inputs, frozen IDs, research phases, tool calls and parameters, scoring formulas, the evidence record
Formatting file	Section order, template, brand and typography (the customer's, if they've shared it), the source-tag convention
Hallucination-audit file (optional)	A QA rule run over the finished output: every figure must trace to a tool call or named public source

Splitting lets you get the data right first, then render it. Debugging an output that is both wrong and badly laid out is twice the work.

Build order

1. Sketch the architecture. A short description of each step and roughly what its output looks like. That's the plan, not the build.
2. Draw the steps as a dependency graph. If steps 2 and 3 both depend on step 1 but not on each other, they run in parallel. Only a real dependency forces an order.
3. Build and validate one step at a time. Write step one, run it, check the output is what you wanted, then write step two. Errors caught at a consequential step cost far less than errors unpicked at the end.

Anatomy of the data-pull file

1. Purpose: one paragraph on what the workflow is for and whose job it serves.
2. Step 0: availability. Start every workflow by following hg-mcp-version-and-availability: check which tools are present and name the fallback for each gated one. Then follow hg-mcp-calling-rules throughout.
3. The customer's domain: their solution areas and, for each, the signals that mark an opportunity. Freeze the stable lists here as IDs (see below).
4. Research phases: each names the exact tool and parameters. Write company_technographic with hg_ids, vendor_ids:[...], max_results:50, not "look up the stack".
5. Scoring: explicit formulas with weights and thresholds, so the output is reproducible rather than a judgement call. Use the calibrated rules from the interpretation skills (within-company intensity, momentum bands, intent only on resolved topics).
6. Output spec: the exact sections, in order, with length budgets.
7. QA checklist the output must pass before delivery (see below).
8. Traceability record: close with a claims-to-tools table, or tag every data point inline with its source. One of the two is mandatory.

Freeze what's stable, resolve what moves

• Resolve stable lists to IDs once, at authoring time, and hard-code them: the customer's product portfolio (product_ids), competitor vendors (vendor_ids), category ids, intent topic_ids, NAICS leaves. Use the free lookups (get_vendor_information, get_product_category, product_search_and_enrich search, list_intent_topics, search_industries_naics_sic).
• Every run-time lookup is a chance to resolve differently; freezing removes that variance.
• Resolve at run time only what genuinely changes: the target account, the date window, the latest signals.
• When you build a competitor set, prefer web research over walking the category taxonomy, then freeze the result as vendor or product IDs.
• Run a category sweep before the workflow claims a competitor is absent.

Name every cost-changing option

If a parameter changes cost or output, write its value in the file. An unnamed option is a decision handed to the model.

Option	Write It As
Web search depth	searchDepth:"basic" or "advanced", plus max_results
Contact phone reveal	revealPhone:false unless the step needs a phone
Time-series size	product_ids:[...] and max_results (each returned product row costs 3)
Enrich sections	fields:[...] listing only the sections used
Intent shape	topic_ids, fields:["topics"], granularity:"global"
Hierarchy depth	depth and mode
Page sizes	limit / max_results on every search

Estimate credits before you ship

Batch tools bill proportionally: rate × companies in the batch. Multiply each step by the expected companies or rows, using the credit table in hg-credit-awareness. Example for 25 accounts:

Step	Calculation	Credits
company_firmographic	0.1 × 25	2.5
company_technographic (filtered)	2 × 25	50
company_intent (resolved topics)	0.1 × 25 calls	2.5
company_install_time_series	3 × 2 products × 5 shortlisted	30
web_search advanced	0.10 × 5	0.5
Free lookups	0	0
Total		85.5

State the estimate as a range with its assumptions. The cache is org-wide and makes repeat runs within the window cheaper (cached calls cost 0), but not fresher: there's no way to force a refresh inside the cache window. Don't design a workflow that reruns "to get updated data" sooner than the data changes. SEC, gov and web tools aren't cached and bill on every run.

Test it before you hand it over

• Fresh-session self-critique. Open a new session, give it the output and the file, and ask: "You're a seller with this account tomorrow. What can you act on? What would you skip? What's missing? Which claims aren't grounded in a tool call?" It catches claims that read well but rest on nothing, and detail that is accurate but useless.
• Determinism test. Run the same inputs several times. Compare the outputs and the tool calls (which tools, which parameters, in which order). Some wording variation is normal. Different scores, different tool calls or different conclusions mean the file leaves too much to the model: freeze more IDs, name more parameters, make the formulas more explicit.
• Check the model. Small models pick tools badly; rule that out before blaming the data.

QA checklist (put a version in every workflow)

• Every figure traces to a named tool call or a named public source.
• No "no data" claim made from an unresolved input, a 422, or a single empty call.
• Contracts gaps reported as "not disclosed"; intent only on resolved topics.
• Modeled figures (spend) hedged; observed ones dated.
• Every cost-changing option named; the credit estimate matches the run.
• Output follows the formatting file and the style skills.

Permitted use

HG MCP data is licensed for agentic workflows, not for populating or maintaining a system of record. Don't author workflows that write HG data back into a CRM, MDM or warehouse on a schedule or per record. Route that need to HG's data feeds or API.

Common pitfalls

1. One giant prompt that pulls data and formats it in the same pass, built all at once and debugged only at the end.
2. Vague research phases ("research the company") that let the model choose tools and parameters.
3. Resolving the portfolio and competitors at run time on every run.
4. Leaving revealPhone, searchDepth, max_results or fields to defaults.
5. Scores as judgement calls instead of written formulas, and no traceability record.
6. Skipping the determinism test or the fresh-session self-critique.
7. Promising fresher data on a rerun inside the cache window, or writing HG data into a system of record.

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-mcp-version-and-availability, hg-credit-awareness, hg-citation-discipline, humanizer, executive-prose-conventions