> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enrichley.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools & Resources

> The two MCP tools, their parameters, costs, and example outputs.

The Enrichley MCP server exposes two tools and one resource. Both tools return structured results so your AI assistant can reason about credit usage and rate limits between calls.

## Credit cost summary

| Tool                           | Credits per call | Notes                                    |
| ------------------------------ | ---------------- | ---------------------------------------- |
| `enrichley_validate_email`     | 1                | Consumes one credit per email validated. |
| `enrichley_get_account_status` | 0                | Free. Use this to check your balance.    |

Credits are deducted from the same balance as the REST API. See [Making API calls](/making-api-calls) for plan details.

## `enrichley_validate_email`

Validate a single email address and return its deliverability status, MX info, and email type.

**When to use it:** any time you want to confirm an email is safe to send to before adding it to a campaign or contact list.

### Parameters

| Field   | Type   | Required | Description                    |
| ------- | ------ | -------- | ------------------------------ |
| `email` | string | Yes      | The email address to validate. |

### Example agent prompts

> *"Validate these emails: [john@acme.com](mailto:john@acme.com), [jane@stripe.com](mailto:jane@stripe.com), [bob@notion.so](mailto:bob@notion.so)"*

> *"Is [jane.doe@example.com](mailto:jane.doe@example.com) safe to send to?"*

The assistant calls `enrichley_validate_email` once per address and summarizes the results.

### Example response

```json theme={null}
{
  "ok": true,
  "status": 200,
  "data": {
    "email": "jane.doe@example.com",
    "valid": true,
    "result": "catch_all_validated",
    "mx_domain": "example.com",
    "email_type": "business",
    "mx_provider": "example",
    "credits_consumed": true,
    "mx_secure_email_gateway": true
  },
  "usage": {
    "rateLimitLimit": 100,
    "rateLimitRemaining": 99,
    "rateLimitReset": 1700000000000,
    "rateLimitResetAt": "2026-05-06T23:59:59.000Z",
    "creditsRemaining": 999999,
    "creditsConsumed": 1
  }
}
```

### `result` values

| Value                 | Meaning                                                | Safe to send? |
| --------------------- | ------------------------------------------------------ | ------------- |
| `ok`                  | The address is valid.                                  | Yes           |
| `catch_all_validated` | The domain is catch-all but the address was validated. | Yes           |
| `catch_all`           | Catch-all domain, address could not be validated.      | No            |
| `invalid`             | The address is invalid.                                | No            |
| `unknown`             | Validation status could not be determined.             | No            |

**Backed by REST endpoint:** [`POST /validate-single-email`](/api-reference/endpoint/email-validation)

## `enrichley_get_account_status`

Return your remaining Enrichley credits and current rate-limit window.

**When to use it:** to check your balance before running a large validation, or to confirm the connection is working.

### Parameters

This tool takes no parameters.

### Example agent prompts

> *"Check my Enrichley credit balance."*

> *"How many email validations do I have left?"*

### Example response

```json theme={null}
{
  "ok": true,
  "status": 200,
  "data": {
    "credits": 999998
  },
  "usage": {
    "rateLimitLimit": 100,
    "rateLimitRemaining": 99,
    "rateLimitReset": 1700000000000,
    "rateLimitResetAt": "2026-05-06T23:59:59.000Z",
    "creditsRemaining": 999998,
    "creditsConsumed": null
  }
}
```

This tool is read-only and does not consume credits.

**Backed by REST endpoint:** [`GET /me`](/api-reference/credits/check-credits)

## The `usage` envelope

Every tool result includes a `usage` object with rate-limit and credit metadata. This lets your AI assistant pace requests and warn you before you run out of credits.

| Field                | Type           | Description                                                                     |
| -------------------- | -------------- | ------------------------------------------------------------------------------- |
| `creditsRemaining`   | number \| null | Credits left on your account after this request.                                |
| `creditsConsumed`    | number \| null | Credits used by this specific request (`0` for free tools, `1` for validation). |
| `rateLimitLimit`     | number \| null | Maximum requests allowed in the current window.                                 |
| `rateLimitRemaining` | number \| null | Requests remaining in the current window.                                       |
| `rateLimitReset`     | number \| null | Unix timestamp in milliseconds when the window resets.                          |
| `rateLimitResetAt`   | string \| null | ISO 8601 form of `rateLimitReset` for human-readable contexts.                  |

<Note>
  Missing values are returned as `null`, never `0`. A `null` means the upstream API did not provide that field for this response (most often on errors).
</Note>

## Errors

When a tool call fails, the response keeps the same envelope shape with `ok: false`:

```json theme={null}
{
  "ok": false,
  "status": 400,
  "data": { "error": "Invalid email format" },
  "usage": {
    "rateLimitLimit": null,
    "rateLimitRemaining": null,
    "rateLimitReset": null,
    "rateLimitResetAt": null,
    "creditsRemaining": null,
    "creditsConsumed": null
  }
}
```

The MCP `isError` flag is set so your AI assistant can detect the failure and decide how to retry or report the issue.

## Resource: `enrichley://usage-guide`

The server publishes a single MCP resource at `enrichley://usage-guide`. It is a markdown document that explains:

* What each `result` value means and whether the address is safe to send to.
* How credits and rate limits work.
* How to interpret tool errors.

AI assistants can read this resource for in-context guidance without you having to paste it into the chat. Most clients will fetch it automatically the first time the Enrichley server is selected.

## Rate limits

The MCP server inherits the same rate limits as the Enrichley REST API:

* 10 requests per second

If you need higher throughput, contact [support@enrichley.io](mailto:support@enrichley.io).