# RevCent MCP Guide: `SearchShipping`

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

---

## Operation Summary

Operation:

```text
SearchShipping
```

Purpose:

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

Use `SearchShipping` when the exact Shipping/Shipment ID is unknown and the user provides a search term such as customer email, customer name, tracking number, phone, address, status, metadata value, product/order context, or another searchable phrase.

---

## Related Links

| Guide | Link |
|---|---|
| Shipping Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShipping.md` |
| Fulfillment Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewFulfillment.md` |
| GetShipment | `https://revcent.com/documentation/markdown/mcp/operation/GetShipment.md` |
| GetShipments | `https://revcent.com/documentation/markdown/mcp/operation/GetShipments.md` |
| EditShipment | `https://revcent.com/documentation/markdown/mcp/operation/EditShipment.md` |
| RefundShipment | `https://revcent.com/documentation/markdown/mcp/operation/RefundShipment.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `SearchShipping` for targeted lookup when the Shipment ID is unknown.

Good search terms:

- tracking number,
- customer email,
- customer name,
- customer phone,
- address,
- Shipment status,
- product name/SKU where indexed,
- metadata value,
- external/customer/internal identifier.

After finding a likely match:

```text
SearchShipping
    ↓
Review result/highlights/score
    ↓
GetShipment
    ↓
Confirm exact Shipment before action
```

---

## Input Schema

Required:

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

Example:

```json
{
  "search_term": "1Z999AA10123456784"
}
```

---

## Output Summary

Search results can include:

| Field | Meaning |
|---|---|
| `item_type` | Usually `shipping` or `shipment`. |
| `id` | 20-character Shipping/Shipment ID. |
| `created_date_unix` | Shipment creation timestamp. |
| `first_name` / `last_name` | Customer or recipient name when returned. |
| `email` | Customer or recipient email when returned. |
| `phone` | Customer or recipient phone when returned. |
| `tracking_number` | Tracking number when returned. |
| `status` | Shipment status when returned. |
| `metadata` | Metadata name/value pairs. |
| `url` | Direct RevCent 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 editing, refunding, disclosing shipment details, or triggering fulfillment/customer support workflows:

```text
SearchShipping
    ↓
Select likely result
    ↓
GetShipment
    ↓
Confirm customer, Shipment status, tracking, and related records
    ↓
Only then take action if appropriate
```

Do not edit or refund a Shipment directly from a search result.

---

## Customer-Facing AI Verification Warning

This operation can help locate sensitive customer, order, shipment, address, fulfillment, tracking, payment, subscription, trial, or lifecycle context.

If this operation is used inside a customer-facing AI flow, such as:

- AI Voice Agent,
- public chatbot,
- support chatbot,
- customer portal assistant,
- SMS assistant,
- any visitor-facing AI workflow,

the AI/MCP client should verify the visitor is actually related to the resulting Shipment before providing details or taking action.

Recommended rule:

```text
Do not provide Shipment 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 customer-facing flow:

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

Recommended secondary verification values:

| Search Input | Secondary Verification Value |
|---|---|
| Tracking number | Customer email or phone from `GetShipment`. |
| Customer name | Customer email or phone from `GetShipment`. |
| Customer email | Secondary phone, order-related value, or another record-backed verification value where available. |
| Address / zip code | Customer email from `GetShipment`. |
| Metadata/external ID | Customer email or phone from the retrieved Shipment. |
| Shipment ID | Customer email from the retrieved Shipment. |

Important:

```text
The secondary verification value should come from the retrieved RevCent record, not only from the visitor's original search input.
```

For example, if the visitor searches by tracking number or name, do not reveal matching Shipment details until they verify a customer email or another secondary value returned by `GetShipment`.

Do not disclose sensitive details such as:

- full customer address,
- unrelated order details,
- payment details,
- internal fulfillment errors,
- fraud/risk logic,
- unrelated customer records,
- internal notes not meant for customers,
- other related records unless the visitor is verified and authorized.

For consequential actions, such as editing shipment status, changing delivery/shipping details, refunding shipping, or triggering support/fulfillment action, require explicit confirmation and follow the relevant operation-specific safety guidance.


---

## Critical Reporting Rule

This Shipment lookup/search operation is **not** a reporting tool.

Do not use this operation for:

- counting,
- aggregations,
- metrics,
- reporting,
- data mining,
- bulk retrieval,
- broad analysis,
- document property searches,
- shipping performance reports,
- shipment status reports,
- fulfillment provider performance reports,
- delivery-rate reports,
- shipment refund reports,
- campaign/shop/product/shipping-method performance metrics.

Use:

```text
BigQueryRunQuery
```

for those purposes.

Important AI/MCP behavior:

```text
If the AI/MCP client 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.
```

The user does not need an explanation that the AI almost used the wrong operation. The correct behavior is to quietly choose the correct operation.


---

## Correct Use vs Incorrect Use

| User Intent | Correct Action |
|---|---|
| “Find the shipment for this tracking number.” | Use `SearchShipping`, then `GetShipment`. |
| “Find the shipment for this customer email.” | Use `SearchShipping`, then `GetShipment`. |
| “Search for this metadata value.” | Use `SearchShipping`, then verify with `GetShipment`. |
| “How many shipments mention X?” | Use `BigQueryRunQuery`, not `SearchShipping`. |
| “Analyze shipments by metadata value.” | Use `BigQueryRunQuery`, not `SearchShipping`. |
| “Find delivery rate by shipping method.” | Use `BigQueryRunQuery`, not `SearchShipping`. |

---

## Example: Correct Lookup Flow

```text
User: Find the shipment for tracking number 1Z999AA10123456784.
```

Correct:

```text
1. SearchShipping with search_term = "1Z999AA10123456784".
2. Review results.
3. GetShipment for the correct result ID.
4. Summarize the exact Shipment.
```

---

## Example: Incorrect Reporting Flow

```text
User: Search all shipments with provider=UPS and tell me delivery rate.
```

Incorrect:

```text
Use SearchShipping 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 tracking number, customer email, phone, or unique metadata values over broad names.
3. Review `highlights` and `score`.
4. Use `GetShipment` after selecting a result.
5. Do not use search results alone for shipment edits or refunds.
6. Do not use search for reporting or data mining.
7. Verify customer identity with a secondary value from `GetShipment` before sharing details in customer-facing AI flows.
8. Use `BigQueryRunQuery` for metrics and analysis.

---

## Final AI/MCP Instruction

Use `SearchShipping` only for targeted full-text lookup of Shipments when the exact Shipment ID is unknown.

In customer-facing AI flows, search results are not proof of authorization. After finding a likely match, use `GetShipment` 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.