CPFHub.io
Start for free

Agent Skills

Ready-made tool/skill definitions to declare in your AI agents. Paste them directly into the system prompt or into your framework's tool configuration. They work with the CPF, Brazil's individual taxpayer ID.

What is an Agent Skill?

A skill is a structured definition (JSON Schema) that tells the LLM when and how to call an external function. The model uses that definition to decide when to look up CPFHub.io during the conversation.

Tool: lookup_cpf

Returns name, gender and date of birth from a Brazilian CPF. It uses the same tool name as the MCP Server.

OpenAI / GPT-4 (JSON Schema)

JSON
{
  "type": "function",
  "function": {
    "name": "lookup_cpf",
    "description": "Looks up data for a Brazilian individual from their CPF. Returns full name, gender and date of birth. Use when the user provides a CPF and you need to verify identity or fill in registration data.",
    "parameters": {
      "type": "object",
      "properties": {
        "cpf": {
          "type": "string",
          "description": "Brazilian CPF with or without formatting. Examples: '12345678909' or '123.456.789-09'."
        }
      },
      "required": ["cpf"]
    }
  }
}

Anthropic Claude (tool_use)

JSON
{
  "name": "lookup_cpf",
  "description": "Looks up data for a Brazilian individual from their CPF. Returns full name, gender and date of birth. Use when the user provides a CPF and you need to verify identity or fill in registration data.",
  "input_schema": {
    "type": "object",
    "properties": {
      "cpf": {
        "type": "string",
        "description": "Brazilian CPF with or without formatting. Examples: '12345678909' or '123.456.789-09'."
      }
    },
    "required": ["cpf"]
  }
}

LangChain (Python)

Python
from langchain.tools import tool
import os
import requests

API_KEY = os.environ["CPFHUB_API_KEY"]

@tool
def lookup_cpf(cpf: str) -> dict:
    """
    Looks up data for a Brazilian individual from their CPF.
    Returns full name, gender and date of birth.
    Use when the user provides a CPF and you need to verify identity.
    
    Args:
        cpf: Brazilian CPF with or without formatting (e.g. '12345678909')
    """
    r = requests.get(
        f"https://api.cpfhub.io/cpf/{cpf}",
        headers={"x-api-key": API_KEY},
        timeout=10,
    )
    if r.status_code == 404:
        # CPF not found is a normal result and does not use a credit
        return {"found": False}
    r.raise_for_status()
    data = r.json()["data"]
    return {
        "found": True,
        "name": data["name"],
        "gender": data["gender"],
        "birthDate": data["birthDate"],
    }

Tool: get_quota_info

Returns the plan, the remaining and used credits and the billing status. Useful for agents that need to check availability before running batch lookups.

OpenAI / GPT-4

JSON
{
  "type": "function",
  "function": {
    "name": "get_quota_info",
    "description": "Returns information about the available credits and the status of the current CPFHub.io plan. Use before starting batch processes to check whether there are enough credits.",
    "parameters": {
      "type": "object",
      "properties": {},
      "required": []
    }
  }
}

Tool: lookup_cpf_realtime

Real-Time Lookup at Receita Federal (Brazil's federal tax authority). It requires the CPF and the date of birth and returns the same fields as POST /cpf/realtime, including deathYear (year of death). The field is always present, as an integer or null. It does not include day or month. null appears when no death is on record or when the value received is invalid. The tool exists on the remote MCP server. The local @cpfhub/mcp package does not include it.

Handler implementation

Regardless of the framework, the handler that runs the tool is always the same:

TypeScript
async function executeTool(name: string, args: Record<string, string>) {
  if (name === 'lookup_cpf') {
    const cpf = args.cpf.replace(/\D/g, '')
    const res = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
      headers: { 'x-api-key': process.env.CPFHUB_API_KEY! },
    })
    const body = await res.json()
    if (!body.success) {
      // Authentication and account errors come with error as a string; lookup errors, error.message
      const message = typeof body.error === 'string' ? body.error : body.error?.message
      return { success: false, status: res.status, error: message }
    }
    return {
      success: true,
      name: body.data.name,
      gender: body.data.gender,
      birthDate: body.data.birthDate,
    }
  }

  if (name === 'get_quota_info') {
    const res = await fetch('https://api.cpfhub.io/quota', {
      headers: { 'x-api-key': process.env.CPFHUB_API_KEY! },
    })
    return res.json() // { success: true, data: { plan, remainingCredits, usedCredits, billingStatus, userId, email } }
  }
}
✦

Tip: tell the model how to handle errors

In the system prompt, tell the agent what to do when the CPF is not found (HTTP 404, "CPF não encontrado na base de dados", meaning "CPF not found in the database"): for example, ask the user to check what they typed. This keeps the agent from getting stuck in a retry loop.

Recommended system prompt

Use this snippet in your agent's system prompt to maximize the quality of the answers:

You have access to the lookup_cpf tool to validate Brazilian identities.

Rules:
- Always confirm the CPF with the user before looking it up
- If the CPF is not found, say the CPF may be incorrect
- Never store or repeat the full CPF in the conversation. Use only the returned name
- Use the result only to confirm identity, not for other purposes

Updated on October 3, 2026