// use case · Developers building AI agents, sales assistants, support copilots and LLM workflows that handle email addresses or company names.
Give your AI agent real email and company data instead of guesses
An LLM asked whether an address is disposable or what a company does will answer from training data, and it may answer differently each run. Define a lookup tool that calls /v1/lookup or /v1/verify from your server code, return only the fields the model needs, and let deterministic code act on verdict and status. The model explains and combines; the API supplies the facts.
The problem
- Our agent confidently told a user a disposable address looked fine.
- The model invents company details when it has never heard of the domain.
- We get different answers for the same email on every run.
- We need the agent to call an API without ever seeing the key.
How pingutil solves it
- 1
Define the tool schema
One string input for the email or domain and an optional flag for the company profile. The same JSON Schema works for Anthropic tool use, OpenAI function calling and an MCP server you host.
- 2
Execute it server-side
Your tool handler calls /v1/lookup or /v1/verify with a key from an environment variable. The model only sees the tool name, description and result.
- 3
Trim the result
Return category, verdict and a few company fields. Smaller results cost fewer tokens and give the model less to misread.
- 4
Keep decisions in code
Block, route or score on verdict.is_spam and status in your own code. Let the agent explain the outcome to the user.
Fields you will use
| Response field | What to do with it |
|---|---|
| category | Give the model a fixed label to reason about |
| verdict.reason | Let the agent explain why an address was flagged |
| company.description | Ground answers about what a company does |
| company.confidence | Tell the model when to hedge |
| status | Report mailbox verification results from /v1/verify |
export const lookupTool = {
name: 'lookup_email_or_domain',
description:
'Classify an email or domain (company, free, disposable, educational, government, isp) ' +
'and return a spam verdict and, for company domains, a short company profile.',
input_schema: {
type: 'object',
properties: { input: { type: 'string', description: 'Email address or domain' } },
required: ['input'],
},
};
export async function runLookupTool({ input }: { input: string }) {
const res = await fetch('https://pingutil.com/v1/lookup', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PINGUTIL_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ input }),
}).then((r) => r.json());
return {
category: res.category,
verdict: res.verdict,
company: res.company && {
name: res.company.name,
description: res.company.description,
confidence: res.company.confidence,
},
};
}Compared with the alternatives
The quick option is letting the model answer from its own knowledge or a web search tool. That works for famous companies and fails on the long tail, with no stable answer to audit. Enterprise data APIs can back an agent too, with deeper data and higher cost; pingutil is free to start, with Enterprise for volume, when classification and company basics are enough.
See provider comparisons →Limits to plan for
- For MCP clients use the hosted server at https://pingutil.com/mcp (three tools, API-key auth). For function calling inside your own agent there is no SDK; you write the tool definition and handler, as in the example.
- Company profiles are themselves LLM-generated from the homepage, so pass confidence to the agent and let it hedge on low values.
- Rate limits apply per account (60 requests a minute), so agents running many parallel calls need a queue or backoff.
Common questions
- Where should the API key live?
- In the code that executes the tool, read from an environment variable or secret store. Never put it in the system prompt or tool description.
- Should the agent decide whether to block a signup?
- Usually not. Let deterministic code act on verdict.is_spam so decisions are reproducible, and let the agent explain or summarize.
- Does this work with MCP?
- Yes. pingutil hosts an MCP server at https://pingutil.com/mcp with verify_email, verify_emails and lookup_email; add it to Claude Code, Codex, Cursor or VS Code with your API key in an Authorization header. You can also wrap the handler in your own server.
Read next
- Guide: Integrate the pingutil email verification API end to end
From API key to production: call /v1/verify, act on valid, invalid, risky and unknown, and handle 429s, rate limits, caching, retries and timeouts correctly.
- Guide: How to qualify inbound B2B leads from the email domain
Score inbound leads from the email alone: company vs free vs ISP domain, company size, industry and funding stage from one API call, mapped to a point model.
- Giving an AI agent an email and domain lookup tool
Tool definitions for Anthropic tool use, OpenAI function calling and MCP that let an LLM agent classify emails and domains with a real API, key kept server-side.
- LLM lead qualification: where a lookup API beats the model
Which lead qualification steps an LLM is good at, which ones a deterministic lookup should own, and a pipeline that puts each in the right place.
- How accurate is LLM-based company enrichment?
Where AI company enrichment is reliable, where it fails (invented funding, stale HQs, the wrong company), and the guardrails that make it safe to use.