# RevCent MCP Operation: `InsertMetadata`

This document explains how MCP/AI clients should use the `InsertMetadata` operation in RevCent. MCP clients can call this operation directly to insert metadata onto specific RevCent items.

It focuses on how metadata can be inserted onto specific RevCent items from:

- AI Voice Agents
- AI Assistants
- Functions
- Direct API calls
- External agents or automation systems

Metadata is useful for marking outcomes, saving parsed results, adding automation context, improving search/reporting, and making future workflows more intelligent.

Sources:
- RevCent V2 API schema for `InsertMetadata`
- RevCent V2 API schema for `GetMetadata`
- RevCent V2 API schema for `GetMetadataEntry`
- RevCent metadata and BigQuery/reporting behavior

---

## Operation Summary

`InsertMetadata` inserts one or more metadata entries onto a specific RevCent item.

A metadata entry is a name/value pair:

```json
{
  "name": "ai_voice_outcome",
  "value": "customer_requested_callback"
}
```

The operation requires:

```text
item_type
item_id
metadata
```

Optional:

```text
cascade
```

Important:

```text
InsertMetadata adds metadata to a specific item.
It is not the same as creating a Key Value.
It is not the same as editing a schema field.
```

Use it when the goal is to attach custom name/value context to a RevCent record, but only when that context is useful, actionable, reportable, automatable, profitable, or explicitly requested by the user.

---

---

# InsertMetadata as an AI Assistant / AI Voice Agent System Action

AI Assistants and AI Voice Agents have access to the `InsertMetadata` system action.

This means metadata does not always need to be inserted by an external API client or separate Function. Metadata can be inserted directly from within an AI Assistant step or during an AI Voice Agent call when the assistant or voice agent has enough context to determine the correct item and metadata outcome.

Important:

```text
AI Assistants can insert metadata within an AI Assistant step by using the InsertMetadata system action.
AI Voice Agents can insert metadata during or after a voice call by using the InsertMetadata system action.
```

This is useful because AI Assistants and AI Voice Agents often produce structured outcomes during conversations.

Examples:

```text
The AI Assistant identifies that the customer wants a refund explanation.
The AI Voice Agent determines that the customer requested a callback.
The AI Assistant parses that the customer is interested in a subscription.
The AI Voice Agent detects that a customer says they will retry payment tomorrow.
The AI Assistant determines that a chargeback should be escalated.
```

Those outcomes can be saved directly as metadata on the relevant RevCent item.

---

## Why System Action Access Matters

Because AI Assistants and AI Voice Agents can use `InsertMetadata` directly, they can turn conversation results into durable RevCent data.

This makes the AI interaction useful beyond the live conversation.

The metadata can later be used by:

```text
Search operations
BigQueryRunQuery
Customer groups
Functions
AI Assistants
AI Voice Agents
External AI agents
Human support teams
Reporting dashboards
Revenue recovery workflows
```

Example flow:

```text
AI Voice Agent speaks with customer
  ↓
Customer says they want a callback tomorrow
  ↓
AI Voice Agent calls InsertMetadata
  ↓
Metadata is inserted on the customer or salvage_transaction
  ↓
A Function, AI Assistant, external agent, or human support team can act on that metadata later
```

---

## AI Assistant Step Example

An AI Assistant step may determine:

```text
The customer is asking about a refund and should be escalated to support.
```

The AI Assistant can call `InsertMetadata`:

```json
{
  "item_type": "customer",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "ai_assistant_topic",
      "value": "refund_question"
    },
    {
      "name": "ai_assistant_outcome",
      "value": "escalated_to_support"
    }
  ]
}
```

This allows the customer record to carry the result of the AI Assistant interaction.

---

## AI Voice Agent Call Example

During a voice call, the AI Voice Agent may determine:

```text
The customer is willing to retry payment after payday.
```

The AI Voice Agent can call `InsertMetadata`:

```json
{
  "item_type": "salvage_transaction",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "ai_voice_outcome",
      "value": "retry_after_payday"
    },
    {
      "name": "ai_voice_followup_status",
      "value": "followup_needed"
    }
  ]
}
```

This can support downstream salvage workflows and reporting.

---

## AI Voice Agent Callback Example

If a customer asks for a callback:

```json
{
  "item_type": "customer",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "ai_voice_outcome",
      "value": "callback_requested"
    },
    {
      "name": "ai_voice_callback_requested",
      "value": "true"
    },
    {
      "name": "ai_voice_callback_window",
      "value": "tomorrow_afternoon"
    }
  ]
}
```

This metadata can later be searched, reported on, or used by Functions/external agents to schedule follow-up.

---

## AI Assistant Parsing Example

If an AI Assistant parses an unstructured customer message:

```text
"I want to keep the subscription, but I need to update my card next Friday."
```

The AI Assistant can insert:

```json
{
  "item_type": "subscription",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "ai_assistant_parsed_intent",
      "value": "keep_subscription_update_card"
    },
    {
      "name": "ai_assistant_followup_timing",
      "value": "next_friday"
    }
  ]
}
```

This turns conversation understanding into structured operational data.

---

## System Action Safety Rules

When using `InsertMetadata` as an AI Assistant or AI Voice Agent system action, the assistant/agent should follow these rules:

1. Insert metadata only when the item type and item ID are known.
2. Use controlled, consistent metadata names.
3. Use controlled, consistent metadata values.
4. Prefer lowercase snake_case values for report-friendly outcomes.
5. Keep metadata values at or below 255 characters.
6. Avoid long metadata values; store only concise outcomes/segments.
7. Do not insert secrets, private credentials, or sensitive payment data as metadata.
8. Do not use metadata to replace a standard schema field.
9. Use `cascade = true` only when the metadata should apply to related sub-items.
10. Remember that metadata is always inserted to a related customer record regardless of cascade value.
11. Avoid creating many near-duplicate metadata names for similar outcomes.
12. Do not insert multiple metadata entries with the same name for the same item; duplicate names are automatically pruned regardless of value.
13. Insert outcomes that will be useful for later search, reporting, workflow decisions, or human review.
14. Do not flood the metadata index with low-value observations, internal reasoning traces, long summaries, or metadata that will not be acted on.

---

## When AI Assistants / Voice Agents Should Insert Metadata

Good reasons to insert metadata from an AI Assistant or AI Voice Agent:

```text
Conversation outcome was determined.
Customer intent was parsed.
Customer requested follow-up.
Customer declined outreach.
Customer gave a reason for failed payment.
Assistant determined escalation is needed.
Voice agent identified objection type.
Assistant completed a workflow step.
AI parsed a support topic.
AI determined next action.
AI marked an item as reviewed or processed.
```

Poor reasons:

```text
The assistant is unsure of the correct item.
The assistant is guessing the metadata name/value.
The value belongs in a standard schema field.
The value is a secret or credential.
The value is account-wide configuration better suited for Key Values.
The metadata would be too inconsistent to be useful for reporting.
```

---

# MCP Clients Can Insert Metadata Directly

In addition to AI Assistants and AI Voice Agents using the `InsertMetadata` system action, MCP clients can also insert metadata directly by calling the `InsertMetadata` operation.

This is the normal MCP/API path when the client already knows:

```text
item_type
item_id
metadata name/value pairs
whether cascade should be true or false
```

Example MCP/API-style request:

```json
{
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "mcp_outcome",
      "value": "metadata_inserted_by_mcp"
    },
    {
      "name": "automation_source",
      "value": "revcent_mcp"
    }
  ],
  "cascade": false
}
```

This is useful when the MCP client is performing an action such as:

```text
Marking an item as processed.
Saving a parsed result from a user request.
Tagging a sale/customer/subscription for later reporting.
Adding an automation outcome after running another operation.
Saving a routing or workflow decision.
Adding metadata before or after triggering an AI Assistant, AI Voice Agent, or Function.
```

Important:

```text
MCP does not need to route metadata insertion through an AI Assistant, AI Voice Agent, or Function when the MCP client itself has the correct item context and user authorization.
```

The MCP client can call `InsertMetadata` directly.

---

## MCP Direct Insert vs AI System Action

| Path | When to use |
|---|---|
| MCP direct `InsertMetadata` operation | The MCP client is executing the metadata insert as part of an API/MCP workflow. |
| AI Assistant `InsertMetadata` system action | An AI Assistant step determines metadata should be saved during an assistant workflow. |
| AI Voice Agent `InsertMetadata` system action | A voice call determines metadata should be saved during or after the call. |
| Function/API insert | A Function or external API workflow programmatically inserts metadata based on automation logic. |

All of these paths ultimately serve the same purpose:

```text
Insert metadata name/value pairs onto a specific RevCent item.
```

The correct path depends on where the decision is being made.

---

## MCP Direct Insert Safety Rules

When MCP inserts metadata directly, it should follow the same safety rules:

1. Confirm the target `item_type`.
2. Confirm the target `item_id`.
3. Use controlled metadata names.
4. Use controlled metadata values.
5. Keep metadata values at or below 255 characters.
6. Avoid long metadata values; store concise outcomes instead.
7. Do not insert secrets or sensitive payment data.
8. Do not use metadata to replace standard schema fields.
9. Use `cascade = true` only when the metadata should apply to related sub-items.
10. Remember related customer metadata behavior.
11. Prefer metadata that will be useful for future search, reporting, automation, or BigQuery analysis.
12. Do not insert metadata merely because the MCP can; insert it only when useful, actionable, profitable, or explicitly requested.
13. Do not insert multiple metadata entries with the same name for the same item; duplicate names are automatically pruned regardless of value.

# Required Fields

| Field | Type | Required | Description |
|---|---:|---:|---|
| `item_type` | enum string | Yes | The item type the metadata is being inserted to. |
| `item_id` | string | Yes | 20-character ID of the item receiving metadata. |
| `metadata` | array<object> | Yes | Array of metadata name/value pairs. |

---

# Optional Fields

| Field | Type | Required | Description |
|---|---:|---:|---|
| `cascade` | boolean | No | Whether to cascade inserted metadata into related sub-items. Defaults to `false`. |

The schema has:

```json
"additionalProperties": false
```

Do not send unknown fields.

---

# Supported `item_type` Values

`InsertMetadata` supports the following item types:

```text
customer
sale
product_sale
shipping
subscription
subscription_renewal
salvage_transaction
chargeback
fraud_detection
```

Use the correct `item_type` for the item being marked.

Examples:

```text
Insert call outcome metadata on a customer → item_type = customer
Insert checkout variant metadata on a sale → item_type = sale
Insert delivery issue metadata on a shipping item → item_type = shipping
Insert renewal salvage result metadata on a subscription_renewal → item_type = subscription_renewal
Insert chargeback evidence status metadata on a chargeback → item_type = chargeback
```

---

# `item_id`

`item_id` is the 20-character ID of the target item.

Examples:

```json
{
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

MCP/AI should not guess item IDs.

If the item ID is not known, retrieve or search for the item first using the appropriate operation.

---

# `metadata`

`metadata` is an array of name/value objects.

Each object requires:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `name` | string | Yes | Metadata name. Maximum 100 characters. |
| `value` | string | Yes | Metadata value. Maximum 255 characters. Long values are highly discouraged. |

Example:

```json
{
  "metadata": [
    {
      "name": "ai_assistant_outcome",
      "value": "refund_explanation_sent"
    },
    {
      "name": "ai_assistant_confidence",
      "value": "high"
    }
  ]
}
```

Multiple metadata entries can be inserted in one operation.

---

# Duplicate Metadata Names Are Automatically Pruned Per Item

RevCent automatically prunes duplicate metadata names on the same item.

This means an item should not be expected to keep multiple metadata entries with the same `name`, even if the `value` is different.

Example existing metadata on an item:

```json
{
  "name": "landing_page",
  "value": "version_1"
}
```

If `InsertMetadata` later inserts:

```json
{
  "name": "landing_page",
  "value": "version_2"
}
```

RevCent will automatically prune duplicate metadata names for that item.

Important:

```text
Duplicate metadata names are removed by name, regardless of different values.
No special MCP/AI pruning technique is required.
Do not intentionally insert multiple metadata entries with the same name onto the same item.
```

This matters because metadata should represent a single current value for a given metadata name on an item.

Good:

```json
{
  "metadata": [
    {
      "name": "landing_page",
      "value": "version_b"
    },
    {
      "name": "email_version",
      "value": "abandoned_cart_v3"
    }
  ]
}
```

Avoid:

```json
{
  "metadata": [
    {
      "name": "landing_page",
      "value": "version_a"
    },
    {
      "name": "landing_page",
      "value": "version_b"
    }
  ]
}
```

If the business needs to preserve historical changes, do not create duplicate metadata names on the item. Instead, use a different durable mechanism such as notes, events, a document, an external log, or a deliberately named historical metadata strategy approved by the user.

---

## Duplicate Name Design Guidance

MCP/AI should treat metadata names as unique per item.

Before inserting metadata, MCP/AI should consider whether the metadata is intended to:

```text
Set or update the current value for a metadata name.
Add a new independent business dimension.
Record an explicit user-requested label.
```

If a metadata name already exists on the item, inserting the same name with a new value should be understood as replacing/pruning the duplicate-name state, not adding another separate value.

Example:

```text
Existing: checkout_page = version_a
Insert: checkout_page = version_b
Result: the item should not retain two checkout_page metadata entries.
```

This is useful when metadata represents the latest/current state:

```text
ai_voice_outcome = callback_requested
chargeback_evidence_status = document_created
external_sync_status = sent_to_warehouse
checkout_page = version_b
```

But it also means MCP/AI should not use duplicate metadata names to represent multiple outcomes.

Bad:

```text
ai_assistant_outcome = refund_policy_explained
ai_assistant_outcome = escalated_to_support
```

Better:

```text
ai_assistant_outcome = escalated_to_support
ai_assistant_topic = refund_question
```

or, if only one durable outcome is needed:

```text
ai_assistant_outcome = escalated_to_support
```


---

---

---

# Metadata Name Length Limit

Metadata names have a maximum length of:

```text
100 characters
```

MCP/AI must keep every metadata `name` at or below this limit.

Metadata names should be short, stable, descriptive, and reusable.

Good names:

```text
ai_voice_outcome
ai_assistant_outcome
checkout_page
email_version
chargeback_evidence_status
external_sync_status
```

Avoid long or overly specific names:

```text
ai_voice_agent_customer_requested_callback_after_discussing_failed_payment_reason
assistant_detected_customer_interested_in_subscription_after_discount_offer
```

Long names make metadata harder to search, report on, group, and maintain.

Recommended rule:

```text
Metadata name = concise reusable business dimension, max 100 characters.
Metadata value = concise controlled segment/outcome, max 255 characters.
```

# Metadata Value Length Limit

Metadata values have a maximum length of:

```text
255 characters
```

MCP/AI must keep every metadata `value` at or below this limit.

Long metadata values are highly discouraged even when they are under the limit.

Metadata should usually be a short, controlled, report-friendly value, not long-form text.

Good values:

```text
callback_requested
refund_policy_explained
version_b
document_created
medium_risk
sent_to_warehouse
```

Bad values:

```text
A full call transcript
A long AI summary
A full customer message
A paragraph explaining everything that happened
A JSON blob containing many fields
A complete internal reasoning trace
```

If the information is long-form, use a more appropriate storage mechanism, such as a note, transcript, document, log, or external system, rather than metadata.

Recommended rule:

```text
Metadata name = concise business dimension.
Metadata value = concise controlled segment/outcome.
```

Examples:

```json
{
  "name": "ai_voice_outcome",
  "value": "callback_requested"
}
```

```json
{
  "name": "chargeback_evidence_status",
  "value": "document_created"
}
```

Avoid using metadata values for verbose details. Save the concise outcome as metadata, and store long supporting detail elsewhere.

# `cascade`

`cascade` determines whether inserted metadata should be cascaded into related sub-items.

Default:

```json
"cascade": false
```

The schema states:

```text
If inserting to sale, any shipping, subscriptions, etc. related to the sale will also have the metadata automatically inserted when cascade is true.
Metadata will always be inserted to a related customer record regardless of cascade value.
```

This is very important.

## When `cascade = false`

Metadata is inserted onto the target item.

Additionally, a related customer record receives the metadata regardless of the cascade value.

Use this when the metadata is mostly about the target item and should not be broadly copied to related sub-items.

Example:

```json
{
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "ai_checkout_review",
      "value": "address_mismatch_detected"
    }
  ],
  "cascade": false
}
```

## When `cascade = true`

Metadata is inserted onto the target item and related sub-items where applicable.

Example:

```json
{
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "campaign_batch",
      "value": "spring_2026_test_b"
    }
  ],
  "cascade": true
}
```

Potential impact:

```text
Sale receives metadata.
Related customer receives metadata.
Related shipping/subscription/other sale-related sub-items may receive metadata.
```

Use cascade only when the metadata should logically apply to the related records.

---

# Metadata Is for Item-Specific Context

Use metadata when storing information about a specific item or related customer.

Examples:

```text
This sale came from checkout page version B.
This customer was contacted by an AI Voice Agent.
This salvage transaction was recovered by AI Assistant workflow X.
This chargeback has document evidence prepared.
This fraud detection was reviewed by an automated Function.
This subscription renewal failed after a specific outreach attempt.
```

Do not use metadata for global account-wide values.

For global values, use Key Values.

---

# Metadata vs Key Values

Metadata and Key Values are different.

| Feature | Scope | Use |
|---|---|---|
| Metadata | Attached to a specific item/record | Item context, attribution, outcomes, labels, parsed results, automation markers. |
| Key Value | Account-wide by key | Shared config, state, feature flags, pointers, reusable values. |

Wrong:

```text
Use InsertMetadata to store a global support email.
```

Correct:

```text
Use CreateKeyValue for a global support email.
```

Wrong:

```text
Use CreateKeyValue to mark a specific sale as page B.
```

Correct:

```text
Use InsertMetadata on the sale with checkout_page = version_b.
```

---

# Metadata vs Schema Fields

Metadata should not replace normal schema fields.

If a value already belongs to a standard schema property, use the schema field.

Examples of known schema fields:

```text
first_name
last_name
email
phone
state
postal_code
status
approved
transaction_id
gateway
amount
created_date_unix
```

Use metadata for custom context not already represented by standard fields.

Examples:

```text
checkout_page = version_b
ai_voice_outcome = callback_requested
email_version = abandoned_cart_v4
facebook_post_id = post_987654
fraud_review_result = suspicious_but_allowed
```

---

# Why InsertMetadata Is Useful

Metadata can improve:

- Search
- Reporting
- BigQuery analysis
- Automation
- Customer segmentation
- AI Assistant logic
- AI Voice Agent logic
- Function workflows
- External AI agent monitoring
- Conversion attribution
- Internal operations
- Outcome tracking
- Revenue recovery workflows

It allows automation systems to write useful context back to RevCent records. This should be meaningful context, not noisy logging or low-value metadata that pollutes the metadata index.

---

# Search and Reporting Value

Inserted metadata can later be discovered through:

```text
GetMetadata
GetMetadataEntry
```

It can be used in:

```text
Search operations
BigQueryRunQuery
Customer groups
Functions
AI workflows
Reporting dashboards
External tools
```

Examples:

```text
Search sales where ai_assistant_outcome = refund_explanation_sent.
Run BigQuery report by checkout_page.
Group customers where ai_voice_outcome = requested_callback.
Analyze chargebacks where evidence_status = document_created.
Report recovery rate by salvage_ai_strategy.
```

---

# AI Voice Agent Use Cases

Important:

```text
AI Voice Agents can call the InsertMetadata system action during a voice call, so the voice agent can save call outcomes, parsed intent, callback requests, salvage results, and other structured call data directly onto the relevant RevCent item.
```


AI Voice Agents can use metadata to mark only durable, high-value call outcomes that should drive follow-up, reporting, segmentation, or automation.

This is especially useful because calls often produce valuable structured outcomes that should be saved back to the related RevCent item.


## Example: Mark Customer Requested Callback

Target item:

```text
customer
```

Request:

```json
{
  "item_type": "customer",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "ai_voice_outcome",
      "value": "callback_requested"
    },
    {
      "name": "ai_voice_callback_time",
      "value": "2026-06-01T14:00:00-04:00"
    }
  ]
}
```

Use case:

```text
The AI Voice Agent learned that the customer wants a callback at a specific time.
Future workflows can search, report, or trigger follow-up based on the metadata.
```

## Example: Mark Failed Sale Salvage Call Outcome

Target item:

```text
salvage_transaction
```

Request:

```json
{
  "item_type": "salvage_transaction",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "ai_voice_salvage_outcome",
      "value": "customer_requested_new_card_link"
    },
    {
      "name": "ai_voice_decline_reason",
      "value": "insufficient_funds"
    }
  ]
}
```

Use case:

```text
The voice call parsed why the sale failed and what the customer wants next.
A Function or external AI agent can follow up based on the metadata.
```

## Example: AI Voice Agent Filter Result

Target item:

```text
customer
```

Request:

```json
{
  "item_type": "customer",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "ai_voice_filter_result",
      "value": "do_not_call_low_intent"
    }
  ]
}
```

Use case:

```text
A pre-call or post-call automation can mark why a customer was excluded from calls.
```

---

# AI Assistant Use Cases

Important:

```text
AI Assistants can call the InsertMetadata system action inside an AI Assistant step, so the assistant can save conversation outcomes, parsed intent, workflow status, escalation reasons, and next-action markers directly onto the relevant RevCent item.
```


AI Assistants can use metadata to mark only durable, high-value assistant outcomes that should drive follow-up, reporting, segmentation, or automation.


## Example: Mark Support Outcome on Customer

Target item:

```text
customer
```

Request:

```json
{
  "item_type": "customer",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "ai_assistant_outcome",
      "value": "refund_policy_explained"
    },
    {
      "name": "ai_assistant_followup_status",
      "value": "awaiting_customer_response"
    }
  ]
}
```

Use case:

```text
The assistant completed a support interaction and marked what happened.
A customer support team or another AI Assistant can later continue with context.
```

## Example: Mark Sale Parsing Result

Target item:

```text
sale
```

Request:

```json
{
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "ai_assistant_parsed_offer",
      "value": "two_bottle_bundle"
    },
    {
      "name": "ai_assistant_customer_intent",
      "value": "interested_in_subscription"
    }
  ],
  "cascade": false
}
```

Use case:

```text
An AI Assistant parsed a conversation or sale context and marked the sale for future reporting or automation.
```

## Example: Mark Escalation Reason

Target item:

```text
customer
```

Request:

```json
{
  "item_type": "customer",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "ai_assistant_escalation_reason",
      "value": "billing_dispute"
    },
    {
      "name": "ai_assistant_confidence",
      "value": "medium"
    }
  ]
}
```

Use case:

```text
The customer can be searched, grouped, or routed to a human support team based on AI-detected escalation reason.
```

---

# Function Use Cases

Functions can call `InsertMetadata` through API workflows or internal operation access where available to write structured outcomes back to RevCent items.

Functions are especially useful because they can run based on events, scheduled jobs, filters, API-direct triggers, AI Assistant steps, AI Voice Agent filters/pre-agent logic, or other automation pathways.


## Example: Mark Function Processed a Sale

Target item:

```text
sale
```

Request:

```json
{
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "function_processed",
      "value": "fraud_review_v2"
    },
    {
      "name": "function_outcome",
      "value": "passed_review"
    }
  ]
}
```

Use case:

```text
Prevents duplicate processing and allows reporting on automated outcomes.
```

## Example: Mark External Sync Status

Target item:

```text
shipping
```

Request:

```json
{
  "item_type": "shipping",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "external_sync_status",
      "value": "sent_to_warehouse"
    },
    {
      "name": "external_sync_provider",
      "value": "custom_erp"
    }
  ]
}
```

Use case:

```text
A Function syncs data to an external warehouse/ERP and marks the shipping item so future runs know the sync occurred.
```

## Example: Mark Rule-Based Routing Result

Target item:

```text
subscription_renewal
```

Request:

```json
{
  "item_type": "subscription_renewal",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "renewal_route_decision",
      "value": "manual_review"
    },
    {
      "name": "renewal_rule_matched",
      "value": "high_value_customer_decline"
    }
  ]
}
```

Use case:

```text
Future automation can search for renewals routed to manual review and report on why that happened.
```

---

# Direct API Call Use Cases

Direct API calls can insert metadata from external systems, custom websites, checkout flows, third-party shops, external AI agents, CRMs, warehouses, support platforms, or business intelligence tools.


## Example: Custom Checkout Adds Page Version

Target item:

```text
sale
```

Request:

```json
{
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "checkout_page",
      "value": "version_b"
    },
    {
      "name": "checkout_experiment",
      "value": "spring_2026"
    }
  ],
  "cascade": true
}
```

Use case:

```text
Later, BigQuery can compare revenue, decline rate, refund rate, or chargeback rate by checkout page version.
```

## Example: External AI Agent Adds Risk Classification

Target item:

```text
fraud_detection
```

Request:

```json
{
  "item_type": "fraud_detection",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "external_ai_risk_classification",
      "value": "medium_risk"
    },
    {
      "name": "external_ai_model",
      "value": "risk_model_v4"
    }
  ]
}
```

Use case:

```text
External AI or internal analysis can classify risk and save the outcome on the fraud detection item.
```

## Example: Chargeback Workflow Adds Evidence Status

Target item:

```text
chargeback
```

Request:

```json
{
  "item_type": "chargeback",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "chargeback_evidence_status",
      "value": "document_created"
    },
    {
      "name": "chargeback_mitigation_vendor",
      "value": "vendor_a"
    }
  ]
}
```

Use case:

```text
Chargeback mitigation workflows can mark which chargebacks have evidence prepared.
```

---

# Updating Automated Outcomes

`InsertMetadata` is useful for updating automated outcomes because metadata can act as a durable marker of what happened.

Examples:

```text
ai_voice_outcome = customer_interested
ai_assistant_outcome = escalated_to_human
function_processed = fraud_review_v2
external_sync_status = sent
chargeback_evidence_status = document_created
salvage_strategy = sms_then_voice
```

These outcomes can then be used by:

```text
Search operations
BigQuery reports
Customer groups
Functions
AI Assistants
AI Voice Agents
External systems
Human support teams
```

---

# Parsing and Structured Extraction

AI systems can parse unstructured input and save structured results as metadata.

Sources of unstructured input may include:

```text
Call transcript
Chat transcript
Support note
Customer message
Decline reason text
Chargeback narrative
External webhook payload
Product review
Email reply
```

AI can parse:

```text
intent
sentiment
topic
risk category
reason for decline
requested follow-up time
preferred product
customer objection
refund reason
chargeback evidence status
```

Then `InsertMetadata` saves the structured result.

Example:

```json
{
  "item_type": "customer",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "parsed_customer_intent",
      "value": "wants_discount"
    },
    {
      "name": "parsed_sentiment",
      "value": "neutral"
    }
  ]
}
```

This makes AI parsing results searchable, reportable, and usable by later automation.

---

---

# Do Not Flood the Metadata Index

`InsertMetadata` should be used intentionally.

MCP clients, AI Assistants, AI Voice Agents, Functions, and external automation systems should not insert useless, low-value, noisy, speculative, or overly granular metadata into items.

Every inserted metadata name/value pair becomes part of the account's metadata ecosystem and may become discoverable through:

```text
GetMetadata
GetMetadataEntry
Search operations
BigQueryRunQuery
Customer groups
Automation workflows
AI workflows
Human support workflows
```

If automation inserts too much meaningless metadata, it can pollute the user's metadata index and make future searching, reporting, filtering, and workflow design harder.

---

## Why Metadata Index Discipline Matters

Metadata is powerful because it creates business dimensions for search, reporting, segmentation, and automation.

However, metadata becomes less useful when the account has too many low-value names or inconsistent values.

Bad metadata creates problems such as:

```text
Metadata index clutter.
Harder report building.
Confusing duplicate metadata names.
Messy BigQuery grouping.
More difficult customer segmentation.
Unclear automation behavior.
Search results polluted with low-value labels.
Human users unable to tell which metadata matters.
AI/MCP systems choosing the wrong metadata name/value later.
```

Metadata should improve business intelligence, not create noise.

---

## Insert Only Useful Metadata

MCP/AI systems should insert metadata only when it is:

```text
Actionable.
Profitable.
Useful for reporting.
Useful for future search.
Useful for automation.
Useful for customer segmentation.
Useful for AI/human follow-up.
Useful for preventing duplicate processing.
Explicitly requested by the user.
```

Good metadata usually helps answer a future question or trigger a future action.

Examples:

```text
ai_voice_outcome = callback_requested
ai_assistant_outcome = escalate_to_support
checkout_page = version_b
chargeback_evidence_status = document_created
function_processed = renewal_review_v1
salvage_strategy = sms_then_voice
parsed_customer_intent = wants_discount
```

These can drive:

```text
Follow-up workflows.
Revenue recovery.
Support escalation.
BigQuery reports.
Search filters.
Customer groups.
AI Assistant logic.
AI Voice Agent logic.
Function idempotency.
```

---

## Do Not Insert Metadata Just Because You Can

MCP/AI should not insert metadata for every small observation.

Bad examples:

```text
ai_saw_customer_name = true
ai_message_length = 182
ai_said_hello = true
ai_used_polite_tone = true
random_note = customer_seemed_ok
temporary_flag = maybe
processing_timestamp_every_step = 1770000000
assistant_step_number = step_14
```

These are usually not useful for search, reporting, automation, or profit.

They clutter the metadata index.

---

## Explicit User Request Exception

If the user explicitly asks to insert a specific metadata name/value pair, MCP/AI may insert it even if the immediate usefulness is not obvious.

Example:

```text
User: Add metadata internal_review_batch = may_2026 to this sale.
```

In that case, MCP/AI can insert it because the user clearly requested it.

However, MCP/AI should still ensure:

```text
The item_type is correct.
The item_id is correct.
The metadata name/value is exactly what the user wants.
The value is not a secret, credential, or sensitive payment data.
The metadata is not better represented by a normal schema field.
```

---

## Actionability Test Before Inserting Metadata

Before inserting metadata, MCP/AI should ask internally:

```text
Will this metadata be useful later?
Will it help search, reporting, automation, segmentation, or human review?
Will it help produce revenue, recover revenue, reduce risk, improve support, or prevent duplicate work?
Is the value controlled and consistent enough to group/report on later?
Did the user explicitly ask for this metadata?
```

If the answer is no, do not insert it.

---

## Metadata Should Represent Business Meaning

Prefer metadata that represents a meaningful business event, decision, segment, or outcome.

Good:

```text
ai_voice_outcome = callback_requested
refund_reason = product_not_received
chargeback_evidence_status = document_created
checkout_page = version_b
external_sync_status = sent_to_warehouse
customer_intent = wants_subscription
```

Poor:

```text
ai_finished = yes
call_happened = true
some_status = done
misc = important
note = good_call
```

Good metadata has clear future use.

Poor metadata is vague and usually becomes clutter.

---

## Avoid Creating New Metadata Names for Every Tiny Variant

Do not create separate metadata names for every minor variation.

Bad:

```text
ai_voice_callback_requested
ai_voice_customer_requested_callback
voice_callback_request
callback_request_from_voice
```

Better:

```text
ai_voice_outcome = callback_requested
```

Use one stable metadata name with controlled values.

This keeps the metadata index clean and makes BigQuery grouping easier.

---

## Avoid Overly Unique Metadata Values Unless Needed

Some unique values are useful, such as external IDs, click IDs, or request IDs.

But high-cardinality values should be inserted only when they serve a clear purpose.

Potentially useful high-cardinality metadata:

```text
external_order_id
facebook_click_id
chargeback_case_id
warehouse_batch_id
tracking_session_id
```

Usually not useful:

```text
ai_generated_random_uuid_for_every_step
full_message_text_as_metadata
entire_call_transcript_as_metadata_value
timestamp_for_every_minor_action
```

Large or overly unique values can make metadata harder to use for reporting.

If the data is long-form text, a note, a transcript, or a document may be more appropriate than metadata.

---

---

## Do Not Use Metadata as a Transcript or Summary Store

Metadata should not be used to store long call transcripts, chat transcripts, full summaries, long AI observations, or detailed reasoning.

For AI Voice Agents and AI Assistants, metadata should capture the concise actionable outcome.

Good:

```text
ai_voice_outcome = callback_requested
ai_assistant_outcome = escalated_to_support
```

Bad:

```text
ai_voice_summary = customer_said_a_lot_of_things_and_then_maybe_wanted_a_callback_but_was_not_sure
ai_assistant_verbose_result = send_a_follow_up_email_with_a_discount_and_then_maybe_call_them_later_if_they_do_not_respond
```

If details are needed, store them in a note, transcript, document, or other appropriate record, and use metadata only as the concise marker that helps find, report, or automate around the item.

## MCP/AI Voice Agent/AI Assistant Rule

For MCP clients, AI Voice Agents, and AI Assistants:

```text
Do not flood metadata.
Do not insert metadata just to log everything.
Do not insert metadata for internal reasoning traces.
Do not insert metadata for every intermediate step.
Only insert metadata that is useful, actionable, profitable, reportable, searchable, or explicitly requested.
```

This is especially important for AI systems because they can generate many observations quickly.

AI systems should insert only the final, durable, business-relevant outcome unless the user specifically wants more detailed metadata.

---

## Examples of Useful vs Useless Metadata

| Situation | Useful Metadata | Avoid |
|---|---|---|
| AI Voice Agent call | `ai_voice_outcome = callback_requested` | `ai_voice_said_hi = true` |
| AI Assistant support chat | `ai_assistant_outcome = escalate_to_support` | `assistant_message_count = 9` |
| Function processed renewal | `function_processed = renewal_review_v1` | `function_started = true` for every item |
| Checkout experiment | `checkout_page = version_b` | `button_color_seen = blue` unless intentionally testing button color |
| Chargeback workflow | `chargeback_evidence_status = document_created` | `chargeback_page_opened = true` |
| External sync | `external_sync_status = sent_to_warehouse` | `sync_attempt_timestamp` for every retry unless needed |
| Revenue recovery | `salvage_strategy = sms_then_voice` | `ai_thought_customer_might_reply = maybe` |

---

## Metadata Quality Standard

Before inserting metadata, the metadata should meet this standard:

```text
It has a clear business purpose.
It is likely to be searched, reported, segmented, or acted on later.
It uses a stable metadata name no longer than 100 characters.
It uses a controlled value.
It is not duplicative of another metadata name/value.
It is not a normal schema field.
It is not account-wide configuration better suited for Key Values.
It is not a secret or sensitive payment data.
It will not unnecessarily pollute the metadata index.
```

If metadata does not meet this standard, do not insert it unless the user explicitly requested it.

# Naming Strategy

Metadata names should be consistent, descriptive, reusable, and no more than 100 characters.

Good names:

```text
ai_voice_outcome
ai_assistant_outcome
function_processed
checkout_page
email_version
facebook_post_id
chargeback_evidence_status
external_sync_status
parsed_customer_intent
```

Poor names:

```text
thing
status
data
result
x
misc
```

Avoid vague names unless the value is highly controlled.

Also avoid creating many duplicate names for the same concept:

```text
ai_outcome
ai_result
assistant_outcome
assistant_result
```

Choose one naming convention.

---

# Value Strategy

Metadata values should also be consistent, concise, and no more than 255 characters.

Good values:

```text
callback_requested
refund_policy_explained
document_created
version_b
passed_review
medium_risk
sent_to_warehouse
```

Poor values:

```text
Callback Requested
customer requested callback
callback
cb requested
CALLBACK_REQUESTED
```

Pick a style and reuse it.

Recommended style:

```text
lowercase_snake_case
```

This makes BigQuery grouping and filtering easier.

Metadata values are not for long-form notes, transcripts, detailed summaries, or verbose AI outputs. Use short controlled values.

---

# Exact Names and Values Matter

Metadata names and values can be used for search, grouping, and reports.

Therefore, inconsistent naming creates messy reports.

Example messy values:

```text
Facebook
facebook
FB
Meta
```

A report may treat these as separate values unless normalized.

MCP/AI should prefer stable controlled values when inserting metadata.

---

# Cascade Strategy

Use `cascade = true` only when metadata should logically apply to related sub-items.

## Good cascade use cases

```text
campaign_batch applies to sale, subscription, shipping, and customer.
checkout_page applies broadly to the sale and related sub-items.
source/affiliate attribution should be available on related records.
```

## Poor cascade use cases

```text
shipping_label_printed should probably only apply to shipping.
chargeback_evidence_status should probably only apply to chargeback.
fraud_review_result should probably only apply to fraud_detection or sale depending on context.
```

Remember:

```text
Metadata is always inserted to a related customer record regardless of cascade value.
```

MCP/AI should explain this behavior when inserting metadata tied to a customer-related item.

---

# InsertMetadata and GetMetadata / GetMetadataEntry

After metadata is inserted, the metadata name becomes part of the metadata index.

Use:

```text
GetMetadata
```

to retrieve metadata names.

Use:

```text
GetMetadataEntry
```

to retrieve saved values for a specific metadata name.

Important:

```text
GetMetadata returns metadata names only.
GetMetadataEntry returns one metadata name plus up to 500 unique values.
```

This makes inserted metadata discoverable for future reporting and automation.

---

# InsertMetadata and BigQueryRunQuery

Inserted metadata can become useful in BigQuery reports.

Examples:

```text
Revenue by ai_voice_outcome
Decline recovery rate by salvage_strategy
Chargeback win rate by chargeback_evidence_status
Refund rate by ai_assistant_outcome
Sales by checkout_page
External sync success by provider
```

Recommended reporting workflow:

```text
1. Insert metadata onto relevant items.
2. Use GetMetadata to confirm metadata names.
3. Use GetMetadataEntry to inspect values.
4. Use GetBigQueryTables to inspect BigQuery schema.
5. Use BigQueryRunQuery for reporting/aggregation.
```

Do not guess how metadata is stored in BigQuery tables. Use `GetBigQueryTables`.

---

# InsertMetadata and Search Operations

Metadata can also help Search operations find relevant records.

Examples:

```text
Search sales with checkout_page version_b.
Search customers with ai_voice_outcome callback_requested.
Search chargebacks with chargeback_evidence_status document_created.
Search shipping items with external_sync_status sent_to_warehouse.
```

Use Search operations when the user wants individual records.

Use BigQuery when the user wants counts, totals, revenue, grouping, or trends.

---

# Common Patterns

## Idempotency Marker

Use metadata to mark that an automation processed an item.

```json
{
  "name": "function_processed",
  "value": "fraud_review_v2"
}
```

Use case:

```text
Avoid duplicate processing by checking whether this marker already exists.
```

## Workflow Step Marker

```json
{
  "name": "support_workflow_step",
  "value": "awaiting_customer_reply"
}
```

Use case:

```text
Allow AI Assistants, support staff, or external agents to continue from the correct step.
```

## Parsed Outcome

```json
{
  "name": "parsed_refund_reason",
  "value": "product_not_received"
}
```

Use case:

```text
Report refund reasons extracted by AI.
```

## Attribution Marker

```json
{
  "name": "facebook_post_id",
  "value": "post_987654"
}
```

Use case:

```text
Report revenue or refunds by specific social post.
```

## Experiment Marker

```json
{
  "name": "checkout_page",
  "value": "version_b"
}
```

Use case:

```text
Compare checkout performance by page version.
```

---

# MCP/AI Decision Guide

Use `InsertMetadata` when:

```text
The user wants to add custom name/value data to a specific item.
An AI system parsed a result that should be saved on the item.
A Function needs to mark an item as processed.
An AI Voice Agent needs to save call disposition or intent.
An AI Assistant needs to save conversation outcome.
A direct API call needs to attach external system context.
The metadata should later be searchable, reportable, used in automation, support profitable business decisions, or the user explicitly requested the exact metadata.
```

Do not use `InsertMetadata` when:

```text
The user wants to update a normal schema field.
The user wants to save an account-wide Key Value.
The user wants to change a payment profile pointer.
The user wants to store sensitive credentials.
The data should belong to a Function environment variable.
The metadata is low-value, noisy, speculative, or unlikely to be searched/reported/acted on later.
The MCP/AI is only inserting it as an internal log or reasoning trace.
The target item ID is unknown.
```

---

# Validation Checklist

Before calling `InsertMetadata`:

1. User or automation has a clear reason to attach metadata, or the user explicitly requested the exact metadata.
2. Correct `item_type` is selected.
3. `item_id` is known and 20 characters.
4. Each metadata object has `name`.
5. Each metadata object has `value`.
6. Metadata names are consistent, descriptive, and no more than 100 characters.
7. Metadata values are consistent, report-friendly, and no more than 255 characters.
8. Metadata values are concise; long values are avoided.
9. MCP/AI understands whether `cascade` should be true or false.
10. MCP/AI understands metadata is always inserted to a related customer record regardless of cascade value.
11. Metadata is not being used to replace a normal schema field.
12. Metadata is not being used for account-wide Key Values.
13. Sensitive secrets are not being inserted as metadata.
14. If metadata will drive automation, names and values are controlled and predictable.
15. Metadata names are treated as unique per item; MCP/AI is not intentionally inserting duplicate names with different values.
16. If metadata will be used for BigQuery, names and values are stable enough for reporting.
17. The metadata is not useless noise that will overflow or pollute the metadata index.
18. The metadata is actionable, profitable, reportable, searchable, automatable, or explicitly requested by the user.

---

# Example Requests

## Insert AI Voice Agent Outcome on Customer

```json
{
  "item_type": "customer",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "ai_voice_outcome",
      "value": "callback_requested"
    },
    {
      "name": "ai_voice_intent",
      "value": "interested_in_renewal"
    }
  ]
}
```

## Insert AI Assistant Outcome on Sale

```json
{
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "ai_assistant_outcome",
      "value": "offer_explained"
    },
    {
      "name": "ai_assistant_followup_status",
      "value": "email_needed"
    }
  ],
  "cascade": false
}
```

## Insert Function Processing Marker on Subscription Renewal

```json
{
  "item_type": "subscription_renewal",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "function_processed",
      "value": "renewal_review_v1"
    },
    {
      "name": "renewal_review_result",
      "value": "manual_review"
    }
  ]
}
```

## Insert Direct API Attribution Metadata on Sale

```json
{
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "email_version",
      "value": "abandoned_cart_v3"
    },
    {
      "name": "checkout_page",
      "value": "version_b"
    },
    {
      "name": "instagram_post",
      "value": "spring_reel_02"
    }
  ],
  "cascade": true
}
```

## Insert Chargeback Mitigation Metadata

```json
{
  "item_type": "chargeback",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "metadata": [
    {
      "name": "chargeback_evidence_status",
      "value": "document_created"
    },
    {
      "name": "representment_vendor",
      "value": "vendor_a"
    }
  ]
}
```

---

# Output Schema

Successful response:

```json
{
  "api_call_id": "XXXXXXXXXXXXXXXXXXXX",
  "api_call_unix": 1740000000,
  "code": 1,
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "result": "..."
}
```

---

# Key Takeaways

```text
InsertMetadata adds one or more metadata name/value pairs to a specific RevCent item. Duplicate metadata names on the same item are automatically pruned by RevCent regardless of differing values.
```

```text
Supported item types include customer, sale, product_sale, shipping, subscription, subscription_renewal, salvage_transaction, chargeback, and fraud_detection.
```

```text
Metadata can be inserted by AI Voice Agents, AI Assistants, Functions, direct API calls, and external automation systems.
AI Assistants and AI Voice Agents can use the InsertMetadata system action directly during assistant steps or voice calls.
MCP clients can also insert metadata directly by calling the InsertMetadata operation.
```

```text
Metadata is useful for marking outcomes, parsing AI results, updating automation state, improving search, and enabling BigQuery reporting. It should not be used to flood the metadata index with useless or non-actionable values.
```

```text
cascade = true can copy metadata to related sub-items, while metadata is always inserted to the related customer record regardless of cascade value.
```

```text
Use consistent names and values so future search, reports, customer groups, Functions, AI Assistants, and AI Voice Agents can rely on the metadata. Metadata names are limited to 100 characters. Only insert metadata that will be useful later or was explicitly requested by the user.
```


---
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.