# RevCent MCP Guide: `SearchCustomers`

Brief AI/MCP-focused guide for searching RevCent Customers.

---

## Operation Summary

Operation:

```text
SearchCustomers
```

Purpose:

```text
Search previously created Customers using a search term.
```

Use `SearchCustomers` when the exact Customer ID is unknown and the user provides a search term such as customer email, name, phone, address, internal ID, IP address, fingerprint, metadata value, or another searchable phrase.

---

## Related Links

| Guide | Link |
|---|---|
| Customer Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewCustomer.md` |
| GetCustomer | `https://revcent.com/documentation/markdown/mcp/operation/GetCustomer.md` |
| GetCustomers | `https://revcent.com/documentation/markdown/mcp/operation/GetCustomers.md` |
| EditCustomer | `https://revcent.com/documentation/markdown/mcp/operation/EditCustomer.md` |
| EnableCustomer | `https://revcent.com/documentation/markdown/mcp/operation/EnableCustomer.md` |
| DisableCustomer | `https://revcent.com/documentation/markdown/mcp/operation/DisableCustomer.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `SearchCustomers` for targeted lookup when the Customer ID is unknown.

Good search terms may include:

- customer email,
- customer name,
- customer phone,
- address,
- internal ID,
- IP address,
- fingerprint,
- metadata value,
- external/customer/internal identifier.

After finding a likely match:

```text
SearchCustomers
    ↓
Review result/highlights/score
    ↓
GetCustomer
    ↓
Confirm exact Customer before action
```

---

## Input Schema

| Field | Type | Required | Description |
|---|---:|---:|---|
| `search_term` | string | Yes | Single search term or phrase used by the full-text search engine. |

Example:

```json
{
  "search_term": "customer@example.com"
}
```

---

## Output Summary

Search results can include:

| Field | Meaning |
|---|---|
| `item_type` | Always `customer`. |
| `id` | 20-character Customer ID. |
| `created_date_unix` | Customer creation timestamp. |
| `first_name` / `last_name` | Customer name. |
| `address_line_1` / `address_line_2` | Customer address lines. |
| `city` / `state` / `zip` | Customer address fields. |
| `email` | Customer email. |
| `phone` | Customer phone. |
| `internal_id` | User-provided internal Customer ID. |
| `ip_address` | Customer IP address when created. |
| `enabled` | Whether the customer is enabled. |
| `fingerprint` | Customer device fingerprint when tracked. |
| `metadata` | Metadata name/value pairs. |
| `url` | Direct RevCent customer details URL. |
| `highlights` | Fields and values matched by the search. |
| `score` | Search score. Higher means a better match. |

---

## Search Safety Rule

Search results are possible matches.

They are not enough to perform consequential actions.

Before discussing customer details, editing a customer, changing customer status, adding/removing cards, making subscription changes, or taking refund/support action:

```text
SearchCustomers
    ↓
Select likely result
    ↓
GetCustomer
    ↓
Confirm customer identity, status, contact details, and related records
    ↓
Only then take action if appropriate
```

Do not take customer/account/lifecycle actions directly from a search result.

---

## Customer-Facing AI Verification Warning

`SearchCustomers` can locate sensitive customer records.

If this operation is used inside a customer-facing AI flow, such as an AI Voice Agent, chatbot, customer portal assistant, SMS assistant, or other public AI method, AI/MCP should verify that the visitor is actually the customer, or is otherwise authorized, before providing information or taking action.

Recommended rule:

```text
Do not provide Customer details to a public-facing visitor based only on the search input they supplied.
```

Search inputs can be guessed, mistyped, shared, or discovered. A search result is only a possible match, not proof that the visitor is authorized.

Safe flow:

```text
Visitor provides search input
    ↓
AI runs SearchCustomers
    ↓
AI selects likely result
    ↓
AI runs GetCustomer for the selected Customer
    ↓
AI verifies the visitor against a secondary value from the GetCustomer response
    ↓
Only after verification:
        provide limited appropriate details
        or take an allowed action
```

Use a secondary value from the retrieved Customer record, such as `GetCustomer.email`, customer phone, or another record-backed value. The secondary value should come from the retrieved RevCent record, not only from the visitor's original search input.

Do not take account, payment, subscription, refund, or support actions directly from search results.


---

## Critical Reporting Rule

These Customer lookup/search operations are **not** reporting tools.

Do not use this operation for:

- counting,
- aggregations,
- metrics,
- reporting,
- data mining,
- bulk retrieval,
- broad analysis,
- document property searches,
- customer count reports,
- customer lifetime value reports,
- segmentation reports,
- churn/retention reports,
- acquisition reports,
- campaign/shop/product/customer analytics.

Use:

```text
BigQueryRunQuery
```

for those purposes.

Important AI/MCP behavior:

```text
If AI/MCP intended to use this operation for reporting, metrics, aggregation, or data mining and then realizes BigQueryRunQuery is the correct operation, it does not need to tell the user about the correction.

It should simply use BigQueryRunQuery instead.
```



---

## Correct Use vs Incorrect Use

| User Intent | Correct Action |
|---|---|
| “Find the customer for this email.” | Use `SearchCustomers`, then `GetCustomer`. |
| “Find this customer by phone.” | Use `SearchCustomers`, then verify with `GetCustomer`. |
| “Search for this internal ID.” | Use `SearchCustomers`, then verify with `GetCustomer`. |
| “How many customers mention X?” | Use `BigQueryRunQuery`, not `SearchCustomers`. |
| “Analyze customers by metadata value.” | Use `BigQueryRunQuery`, not `SearchCustomers`. |
| “Find customer count by source.” | Use `BigQueryRunQuery`, not `SearchCustomers`. |

---

## Example: Correct Lookup Flow

```text
User: Find the customer for customer@example.com.
```

Correct:

```text
1. SearchCustomers with search_term = "customer@example.com".
2. Review results.
3. GetCustomer for the correct result ID.
4. Summarize the exact Customer after verification.
```

---

## Example: Incorrect Reporting Flow

```text
User: Search all Customers with utm_source=google and tell me customer lifetime value.
```

Incorrect:

```text
Use SearchCustomers repeatedly and aggregate results manually.
```

Correct:

```text
Use BigQueryRunQuery.
```

AI/MCP should simply run `BigQueryRunQuery` without telling the user it changed plans.

---

## Best Practices

1. Use specific search terms.
2. Prefer customer email, phone, internal ID, or unique metadata values over broad names.
3. Review `highlights` and `score`.
4. Use `GetCustomer` after selecting a result.
5. Do not use search results alone for customer/account lifecycle actions.
6. Do not use search for reporting or data mining.
7. Verify customer identity with a secondary value from `GetCustomer` before sharing details in customer-facing AI flows.
8. Use `BigQueryRunQuery` for metrics and analysis.

---

## Final AI/MCP Instruction

Use `SearchCustomers` only for targeted full-text lookup of Customers when the exact Customer ID is unknown.

In customer-facing AI flows, search results are not proof of authorization. After finding a likely match, use `GetCustomer` and verify the visitor with a secondary value from the retrieved record, such as `customer.email`, before providing details or taking action.

Do not use it for reporting, metrics, aggregation, counting, broad analysis, or data mining. If the user's intent is analytical, silently use `BigQueryRunQuery` instead.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.