How AI Agents Use Enrichment Tools With Guardrails

How AI agents use enrichment tools safely comes down to giving the agent a narrow retrieval capability, then keeping decisions and downstream actions under policy control. The useful pattern is not “let the agent find anything.” It is “let the agent request defined fields for defined entities, within a defined spend and review process.”

What enrichment gives an AI agent

Enrichment gives an agent structured facts about a person or company, but only when you define the entity and fields it may retrieve.

There are two related operations with different jobs:

• Search discovers people or companies that match a description or filter set. An agent might search for people by title, seniority, department, location, or employer.
• Enrichment resolves identifiers you already have. For people, that can be a LinkedIn URL, an email address, or a name plus employer. For companies, it can be a domain, name, or LinkedIn URL.

That distinction matters in an AI agent enrichment workflow. A search starts with an audience definition. Enrichment starts with a record from your CRM, event list, product database, or another system where you already hold an identifier.

For a person, an agent can retrieve fields such as:

• Work email
• LinkedIn URL
• Current title
• Normalised seniority
• Normalised department
• Published location and derived country
• Current employer and company domain
• Profile headline
• Company context through company_profile

For a company, it can retrieve its name, domain, LinkedIn URL, location, country, and headline. Company results can also carry firmographics including industry, employee count, founded year, revenue, funding, and monthly visits.

That does not make enrichment unrestricted profile collection. Your agent should request only the fields needed for the task.

If the task is account routing, you may need company_domain, location, and firmographics. If the task is a territory review, title, seniority, department, and location may be enough. If the task requires outbound preparation, work email must be deliberately included in the request.

Field-level data access is a useful design constraint. It turns “enrich this record” into a reviewable instruction:

Resolve this LinkedIn URL. Return title, seniority, department, company, and company_domain. Do not request email or phone.

That is easier to inspect than a broad instruction to “get everything.”

The agent workflow: brief, plan, retrieve, decide

A controlled enrichment agent should translate a business brief into a plan before it retrieves data.

A practical sequence has four stages:

1. Interpret the brief. Identify the business purpose, target entity, exclusions, and intended downstream use.
2. Plan the request. Select search or enrichment, choose allowed fields, identify input records, and set a result limit.
3. Retrieve records. Run the selected tool and retain each item-level result.
4. Decide or route. Summarise the output, create a review queue, or send approved records to a downstream workflow.

Consider two common GTM data automation tasks.

A user says: “Find product leaders at companies in a target market.” The agent should use search because the target people are not yet known. It should define the requested audience, request the fields needed to assess fit, and return a structured result table.

A user says: “Fill missing departments for these CRM contacts.” The agent should use enrichment because the CRM already supplies identities. It should resolve each provided identifier and return only the department field, with enough identity context for a reviewer to match the result to the CRM record.

The agent should not infer a person’s department from a vague description when a structured field is available. It should not guess an employer because the requested name resembles a company in the CRM. Structured outputs and explicit decision rules are more reliable than asking a model to reason from free text alone.

For example, you can specify decision rules such as:

• Accept seniority only when it is one of the supported normalised values.
• Route a person record for review when the resolved employer conflicts with the CRM employer.
• Do not create a contact record from a search result unless an approved workflow permits it.
• Return not_found as an outcome, not as an empty value the agent silently fills from context.

The in-product chat agent can plan a run from a plain-language brief, show what it is about to spend, and return a table for export. That is useful when a human operator needs to review the proposed run before retrieval begins.

Set field, identity, and spend guardrails

Guardrails should constrain the fields, identifiers, result count, and approval path before an agent starts a run.

Start with a field allowlist. Make it specific to the workflow rather than using one broad policy for every agent.

For example:

• An account research agent may request company fields and firmographics.
• A routing agent may request title, seniority, department, location, and company_domain.
• An outbound preparation agent may request email only after a separate approval step.
• A phone field should remain unavailable unless the workflow explicitly needs it and the caller has reviewed the intended use.

Work email and phone are deliberate requests. They should not appear in a generic “enrich every record” instruction.

Email addresses are work addresses found from public sources. They are probed as part of the run and returned with an email status. Phone is different: it is sourced from a LinkedIn profile URL, billed only when returned, and has no deliverability verdict. A phone number must never be described as verified.

Next, require the agent to state its identity inputs and intended result count in its plan. The plan should say whether it will use LinkedIn URLs, supplied emails, names plus employers, company domains, or another supported identifier. This makes overbroad requests visible before execution.

Use result limits as a policy control. A broad audience description can otherwise become a large search without anyone noticing the implied spend or review workload. For larger workflows, divide retrieval from approval:

• The agent drafts the search or enrichment request.
• A human or policy service checks the fields, identifiers, and estimated spend.
• The approved request runs.
• The output enters a review or routing step.

The product returns estimatedCredits in its response envelope. The chat and CSV upload surfaces also show a cost preview before work runs. You can use those signals to enforce your own approval threshold.

The charging model supports narrow requests. A person returned from search costs 0.25 credits. A resolved person enrichment row costs 0.5 credits when at least one requested field is resolved. A work email found costs 2 credits, while email verification is included. A mobile number found costs 10 credits.

Those are useful planning inputs, not reasons to make the agent decide spend alone. The control is still your policy: which fields are allowed, when approval is required, and what business purpose justifies contact data.

Use MCP and API tools for controlled execution

MCP and REST provide two ways to execute the same controlled enrichment workflow.

An MCP client can connect to /api/mcp over Streamable HTTP and use the same API-key-based access model as the REST API. This is useful when your agent runs in a tool-calling environment such as Claude, ChatGPT, Cursor, or Codex.

The MCP server exposes tools for people and company search and enrichment. search_people finds people matching an ideal-customer-profile description, but it returns who they are rather than their email address. If your workflow needs a work email, use enrich_people and ask for fields: ["email"].

That separation is useful for policy enforcement. An agent can first identify a candidate audience, then request approval before enriching selected identities with contact data.

For custom orchestration, logging, and internal policy enforcement, use the REST API under /api/v1. Your service can validate an agent plan before calling:

• POST /api/v1/people/search
• POST /api/v1/people/enrich
• POST /api/v1/companies/search
• POST /api/v1/companies/enrich

You can inspect the generated API contract at /docs and retrieve the OpenAPI document at /api/v1/openapi.

Response handling needs to account for inline and queued work. A people or company search requesting 10 results or fewer can return inline. An enrichment request of 5 rows or fewer can also return inline. In those cases, the response already includes results, and the job has reached a terminal status. There is nothing to poll.

Larger requests are queued. Requests for the email field are queued as well, as are requests sent with async: true or Prefer: respond-async. For queued work, results is null until the job reaches a terminal state. Poll GET /api/v1/jobs/{id} and read job.status.

Polling is free. Do not treat an HTTP 200 response from the job endpoint as proof that the work is complete; that endpoint always returns 200. Read the status instead. Valid job states are queued, running, succeeded, empty, failed, and cancelled.

When results arrive, preserve the wrapper around each item:

{
  "job": {
    "object": "job",
    "id": "job_example",
    "status": "succeeded"
  },
  "results": [
    {
      "position": 0,
      "status": "succeeded",
      "data": {
        "title": "Product Manager",
        "department": "product"
      },
      "evidence": null,
      "error": null
    },
    {
      "position": 1,
      "status": "not_found",
      "data": null,
      "evidence": null,
      "error": null
    }
  ],
  "page": null,
  "estimatedCredits": 0
}

The person or company record is inside data. The item status tells your agent whether a record succeeded, was not found, or failed. Do not discard unresolved rows just because other rows completed.

If your orchestrator retries a request, send the same Idempotency-Key header. That is what makes the retry free and deduplicated. Without that header, a retry is a new request with a new job and a new hold.

Learn more about tool access at /mcp and API behaviour in /docs.

Keep enrichment output from causing unsafe CRM changes

Retrieval should not automatically become writeback.

An enrichment result is a candidate value from a live source. Your CRM field may have ownership rules, a user-entered value, or a value maintained by another system. An agent should not overwrite those fields simply because it retrieved a new title or employer.

Use source-aware update rules for mutable attributes:

• Title: propose an update when the resolved title differs, but retain the existing value until policy allows the change.
• Employer: require review when the employer conflicts with the CRM company, because the mismatch may indicate a role change or an identity mismatch.
• Location: allow a suggested update, but distinguish a published location from a sales territory assignment.
• Department: use the normalised value for routing only when the workflow accepts the supported department vocabulary.

Separate these steps:

1. Retrieve the enrichment result.
2. Compare it with the existing CRM record.
3. Apply conflict and ownership rules.
4. Write, queue for review, or leave unchanged.
5. Record the action taken.

Human-in-the-loop review is appropriate for ambiguous matches, conflicting values, contact creation, list membership changes, and any action that could initiate outreach. The agent can prepare the recommendation. A person or policy service should own the action when the consequence is meaningful.

Keep an audit record in your own system with the original request, identifiers supplied, fields requested, returned values, item outcomes, and downstream action. Enrichments also maintains an append-only usage ledger for charges, but a usage entry is not a complete record of your CRM policy decision.

Design prompts and policies for predictable agent behavior

Predictable agent behavior comes from explicit instructions, structured tool inputs, and clear escalation rules.

A useful instruction names the entity, fields, exclusions, output format, and what to do when the result is uncertain. For example:

For each supplied LinkedIn URL, enrich only title, seniority,
department, company, and company_domain.

Do not request email or phone.
Return one structured outcome per input record.
If the result is not_found or failed, preserve that status.
Do not infer missing values from the person's name, employer, or prior CRM data.
If company conflicts with the CRM employer, mark the record for human review.
Do not write changes to the CRM.

For a company workflow, use equally specific language:

Resolve the supplied company domains.
Return company, location, country, headline, and company context.
Exclude contact data.
Summarize records with missing or conflicting company domains separately.
Do not create accounts or update account ownership.

Your policy should also tell the agent how to handle each non-success outcome:

• No result or empty: report that no matching result was delivered.
• not_found: retain the input identifier and mark it unresolved.
• failed: report the failure without substituting a guessed value.
• Conflicting values: present both the CRM value and retrieved value for review.
• Unsupported field request: stop and revise the request. The field catalogue is closed, so an unsupported field is a validation error rather than an empty column.

Set contact-use boundaries directly in the prompt. Work emails are public-source business addresses, not permission to send messages without considering your own obligations. Phone availability is not a representation that calling is lawful. TCPA, DNC registries, consent requirements, and local rules remain the caller’s responsibility.

Use this deployment checklist before enabling agent tool calling:

• Define the business purpose for each enrichment workflow.
• Allowlist fields by workflow and make email and phone explicit approvals.
• Require a declared identity source and result count before execution.
• Use cost previews and approval rules for broad or contact-data requests.
• Preserve item-level statuses, including not_found and failed.
• Separate retrieval from CRM writeback.
• Route conflicts and sensitive actions to human review.
• Store an audit record of the request, response, and action.
• Use the same Idempotency-Key for a genuine retry.
• Review plan allowances and credit usage at /pricing.