# RevCent MCP Operation: `CreateNote`

This document explains how MCP/AI clients should use the `CreateNote` operation in RevCent.

`CreateNote` creates a short note on a specific RevCent item.

Important:

```text
Note text is limited to 255 characters.
```

Sources:
- RevCent V2 operation schema for `CreateNote`

---

## Operation Summary

`CreateNote` creates a note for a specific item using:

```text
item_type
item_id
text
```

The operation is meant for short human-readable context attached to a RevCent record. To retrieve existing notes, retrieve the details of the item, such as using `GetCustomer` for customer notes.

Examples:

```text
Customer requested callback tomorrow.
Support reviewed refund concern.
AI Voice Agent detected customer wants to retry payment.
Warehouse confirmed address correction.
Subscription renewal manually reviewed.
```

A note should be concise and useful.

---

# Supported Item Types

`CreateNote` supports notes on these item types:

```text
sale
customer
product_sale
shipping
subscription
subscription_renewal
```

Use the correct `item_type` for the item receiving the note.

Examples:

```text
Create a note on a customer → item_type = customer
Create a note on a sale → item_type = sale
Create a note on a shipping record → item_type = shipping
Create a note on a subscription → item_type = subscription
Create a note on a subscription renewal → item_type = subscription_renewal
```

---

# Input Fields

| Field | Type | Required in practice | Description |
|---|---:|---:|---|
| `item_type` | enum string | Yes | The item type the note is being created for. |
| `item_id` | string | Yes | 20-character ID of the item receiving the note. |
| `text` | string | Yes | Text content of the note. Maximum 255 characters. |

The schema has:

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

Do not send unknown fields.

Although the schema may not mark fields as required, a meaningful `CreateNote` call should include all three fields:

```text
item_type
item_id
text
```

---

# `item_type`

Allowed values:

```text
sale
customer
product_sale
shipping
subscription
subscription_renewal
```

Choose the item type that best represents where the note belongs.

| Scenario | Recommended item_type |
|---|---|
| General customer support context | `customer` |
| Note about a specific purchase | `sale` |
| Note about one product in a sale | `product_sale` |
| Note about delivery, tracking, or address issue | `shipping` |
| Note about an ongoing subscription | `subscription` |
| Note about a failed or reviewed renewal | `subscription_renewal` |

---

# `item_id`

`item_id` is the 20-character ID of the item receiving the note.

Example:

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

MCP/AI should not guess item IDs.

If the item ID is not known, retrieve or search for the relevant item first.

---

# `text`

`text` is the note content.

Maximum length:

```text
255 characters
```

The note should be concise, clear, and useful. When summarizing a customer interaction, attempt to condense the interaction into one note rather than creating play-by-play notes.

Good examples:

```text
Customer requested callback tomorrow afternoon.
AI Voice Agent detected retry-after-payday intent.
Support explained refund policy; customer accepted.
Address issue reviewed; customer confirmed corrected address.
Renewal failed; customer plans to update card Friday.
```

Poor examples:

```text
A full call transcript.
A long AI-generated summary.
A full support conversation.
Internal AI reasoning.
Large JSON data.
Secrets, credentials, or payment data.
```

If the information is longer than 255 characters, summarize it or store the long-form content somewhere more appropriate, such as a document, transcript, external system, or structured metadata plus a short note.

---

# Notes vs Metadata

Notes and metadata serve different purposes.

| Feature | Best for |
|---|---|
| Note | Short human-readable context on an item. |
| Metadata | Structured name/value data for search, reports, BigQuery, segmentation, and automation. |

Use a note when a human-readable comment is needed.

Use metadata when the value should be structured, filtered, grouped, reported on, or used by automation.

Example note:

```text
Customer requested callback tomorrow afternoon.
```

Example metadata:

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

Both can be useful together:

```text
Note = concise human context.
Metadata = structured reportable outcome.
```

---

# Notes vs Key Values

Notes are item-specific.

Key Values are account-wide.

| Feature | Scope |
|---|---|
| Note | Attached to one item. |
| Key Value | Account-wide value accessed by key. |

Do not use notes for global configuration.

Examples that should be Key Values, not notes:

```text
support_email
active_payment_profile
daily_report_cursor
vip_ltv_threshold
```

---

# When To Use CreateNote

Use `CreateNote` when the user or automation needs to attach short item-specific human-readable context.

Good use cases:

```text
Customer support note.
AI Assistant interaction summary.
AI Voice Agent call outcome summary.
Function/manual review note.
Shipping issue note.
Subscription renewal follow-up note.
Sale-specific clarification.
```

Do not use `CreateNote` when:

```text
The data is structured and should be reportable.
The data should be a metadata name/value pair.
The data is account-wide configuration.
The data is sensitive credential/payment information.
The data is too long for 255 characters.
The note is useless noise or internal AI reasoning.
```

---

# AI Assistant Use Cases

An AI Assistant may create a note when it has a concise, human-readable outcome from an assistant step.

Examples:

```text
Assistant explained refund policy; customer asked for email follow-up.
Customer asked about subscription; assistant recommended renewal support.
Assistant detected billing dispute and escalated to human support.
```

Example request:

```json
{
  "item_type": "customer",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "text": "Assistant detected billing dispute and escalated to support."
}
```

Important:

```text
Do not store full assistant conversation transcripts as notes.
Do not create play-by-play notes during the assistant interaction; create one concise summary note when the interaction reaches a meaningful stopping point.
Do not store internal AI reasoning as notes.
Keep note text under 255 characters.
```

---

# AI Voice Agent Use Cases

An AI Voice Agent may create a note when it has a concise call outcome worth saving for human review.

Examples:

```text
Customer requested callback tomorrow afternoon.
Customer will retry payment after payday.
Customer declined renewal and asked not to be called again.
Customer confirmed shipping address correction.
```

Example request:

```json
{
  "item_type": "customer",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "text": "Voice call: customer requested callback tomorrow afternoon."
}
```

For reportable voice outcomes, also consider metadata. Do not create play-by-play notes during the call; summarize the call outcome in one concise note whenever possible.

Example metadata:

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

---

# Function Use Cases

Functions may create notes when event-driven or scheduled automation needs to leave human-readable context on an item.

Examples:

```text
Function reviewed renewal and routed to manual review.
Function synced shipment to warehouse.
Function detected high-risk sale and notified support.
Function processed chargeback evidence workflow.
```

Example request:

```json
{
  "item_type": "subscription_renewal",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "text": "Function routed renewal to manual review: high-value decline."
}
```

For idempotency or structured reporting, use metadata instead of, or in addition to, notes.

---

# MCP Direct Use

MCP clients can call `CreateNote` directly when the user asks to add a note or when an MCP workflow needs to add a concise human-readable note to an item.

Example:

```json
{
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "text": "User asked support to review this sale before refund."
}
```

MCP should only create a note when:

```text
The target item is known.
The note text is useful.
The note text is under 255 characters.
The note is not better represented as metadata.
The user requested the note or the workflow clearly requires it.
```

---

---

# Condense Customer Interactions Into a Single Note When Possible

When creating notes from a customer interaction, MCP/AI should attempt to summarize the interaction in one concise note whenever possible.

A note should not be created as a play-by-play during an active customer conversation.

Avoid creating notes like:

```text
Customer said hello.
Customer asked about refund.
Customer paused.
Customer asked another question.
Customer said they might call back.
Customer seemed upset.
```

This creates noisy customer history and makes notes less useful for support teams, BigQuery reporting, and future AI workflows.

Instead, wait until the interaction reaches a meaningful stopping point, then create one concise note that summarizes the interaction as a whole.

Better:

```text
Customer asked about refund policy, declined refund for now, and requested email follow-up.
```

Another good example:

```text
Voice call: customer will retry payment Friday and requested no callback before then.
```

Important:

```text
Notes should summarize a specific interaction in its entirety whenever possible.
Notes should not document every small step while the interaction is still happening.
```

---

## Why Condensed Notes Matter

Condensed notes are better because they:

```text
Keep customer history readable.
Reduce note noise.
Avoid flooding the notes table.
Make support handoff easier.
Improve BigQuery reporting quality.
Make customer-service timeframe analysis cleaner.
Help AI Assistants and AI Voice Agents understand prior interactions faster.
```

Too many granular notes can make it harder to understand what actually happened.

A single good note is usually more valuable than many low-value notes.

---

## When Multiple Notes Are Appropriate

Multiple notes may be appropriate when:

```text
There are separate customer interactions at different times.
A new material event happens after the first note.
A different team or user takes a separate action.
The customer changes their decision later.
A follow-up interaction produces a new outcome.
```

Example:

```text
Note 1, Monday: Customer requested callback Friday to update card.
Note 2, Friday: Customer updated card and asked to resume subscription.
```

This is appropriate because the notes represent separate meaningful interactions.

---

## AI Assistant and AI Voice Agent Guidance

AI Assistants and AI Voice Agents should generally avoid creating notes mid-conversation unless a workflow explicitly requires it.

Preferred pattern:

```text
1. Complete the interaction or reach a meaningful stopping point.
2. Create one concise note summarizing the interaction.
3. Insert metadata separately if structured reporting or automation is needed.
```

Example note:

```text
Assistant resolved billing question and customer requested follow-up email.
```

Example metadata:

```json
{
  "name": "ai_assistant_outcome",
  "value": "billing_question_resolved"
}
```

The note provides human-readable context. The metadata provides structured reporting and automation value.

---

## MCP Rule

MCP/AI should not create a note merely because a customer message was received.

Before creating a note, MCP/AI should ask:

```text
Is the interaction complete or at a meaningful stopping point?
Can this be summarized in one useful note?
Will this note help a future human or AI understand the customer history?
Is this better stored as structured metadata instead?
Is the note under 255 characters?
```

If the answer is no, delay or avoid note creation unless the user explicitly asks for the note.

# Note Text Quality Rules

Good note text should be:

```text
Short.
Clear.
Human-readable.
Relevant to the item.
Useful for future support, review, or workflow context.
Under 255 characters.
```

Avoid note text that is:

```text
Long-form.
Play-by-play updates from a single customer interaction.
Speculative.
Useless noise.
Internal AI reasoning.
Full transcripts.
Secrets or credentials.
Raw payment data.
Duplicate of existing schema fields.
```

---

# Notes and `note.created` Workflows

A created note may be useful as an operational signal.

If the RevCent account has workflows, Functions, AI Assistants, AI Voice Agents, or external automation configured around note creation events, a new note can provide short context for downstream actions.

Example:

```text
Note created on customer: "Customer requested callback tomorrow afternoon."
```

Potential downstream actions:

```text
Function parses note and creates follow-up task.
AI Assistant reviews note and prepares customer response.
External agent monitors notes and escalates urgent cases.
Support team sees note in customer history.
```

If notes are used as automation triggers, keep note text consistent and concise.

For structured automation triggers, metadata may be better than notes.

---

---

# Retrieving Notes

There is no separate `GetNotes` operation described for retrieving notes in bulk.

To retrieve notes, retrieve the details of the item that the notes are attached to.

For example:

```text
If you want notes for a customer, call GetCustomer.
The GetCustomer response includes a notes array containing notes associated with the customer.
```

Conceptual flow:

```text
User asks: "Show me the notes for this customer."
  ↓
MCP identifies the customer_id.
  ↓
MCP calls GetCustomer with customer_id.
  ↓
MCP reads the notes array from the GetCustomer response.
  ↓
MCP presents the notes to the user.
```

Example response shape concept:

```json
{
  "id": "CUSTOMER_ID",
  "email": "customer@example.com",
  "notes": [
    {
      "id": "NOTE_ID",
      "text": "Customer requested callback tomorrow afternoon.",
      "created_date_unix": 1740000000,
      "updated_date_unix": 1740000000,
      "username": "support_user",
      "first_name": "Support",
      "last_name": "User",
      "employee_id": "EMPLOYEE_ID",
      "customer_note_related_type": "customer",
      "customer_note_related_id": "CUSTOMER_ID"
    }
  ]
}
```

The same principle applies to other item types:

```text
To retrieve notes for a sale, retrieve the sale details.
To retrieve notes for a subscription, retrieve the subscription details.
To retrieve notes for a subscription renewal, retrieve the subscription renewal details.
To retrieve notes for a shipping item, retrieve the shipping/shipment details.
To retrieve notes for a product sale, retrieve the product sale details.
```

MCP/AI should not assume notes are retrieved through `CreateNote`.

`CreateNote` creates a note. Item detail operations retrieve the item and its associated notes. For cross-item note search and reporting, `BigQueryRunQuery` can query the `note` table.

---

## CreateNote vs Retrieving Notes

| Goal | Operation Pattern |
|---|---|
| Add a note to an item | Use `CreateNote`. |
| View notes for a customer | Use `GetCustomer` and read the `notes` array. |
| View notes for another item | Retrieve that item’s details and read its notes/associated notes field. |

Example:

```text
CreateNote creates a note on customer X.
Later, GetCustomer(customer_id = X) returns customer details including the notes array.
```

---

## MCP Retrieval Guidance

When the user asks to retrieve, view, list, or summarize notes:

1. Identify the item type.
2. Identify the item ID.
3. Use the appropriate item detail operation.
4. Read the returned `notes` array or note-related field.
5. Present the note text, timestamps, note ID, and creator information when available.

Do not call `CreateNote` when the user is only asking to read notes.

---

# Querying Notes With BigQueryRunQuery

Notes can also be queried through `BigQueryRunQuery`.

RevCent BigQuery includes a `note` table:

```sql
`revcent.user.note`
```

The BigQuery operation documentation describes the `note` table as containing all notes created, whether created through the API or within the web app.

This means notes are not only visible from item detail operations, such as `GetCustomer`; they can also be searched, filtered, aggregated, and analyzed in BigQuery.

Important:

```text
Use item detail operations when you want notes for one specific item.
Use BigQueryRunQuery when you want to search notes, aggregate notes, report on note activity, or analyze customer service behavior across many notes/customers.
```

---

## Use GetBigQueryTables First

Before writing note queries, MCP/AI should call:

```text
GetBigQueryTables
```

to inspect the current `note` table schema.

Do not guess exact field names.

Likely note table concepts may include:

```text
note ID
note text
created date
updated date
related item type
related item ID
customer-related type/id
employee/user/creator fields
```

But MCP/AI must confirm the exact columns using `GetBigQueryTables` before writing final SQL.

BigQuery table references must be fully qualified and wrapped in backticks:

```sql
`revcent.user.note`
```

---

## BigQueryRunQuery vs Item Detail Retrieval

| Goal | Best approach |
|---|---|
| View notes for one customer | `GetCustomer`, then read the `notes` array. |
| View notes for one sale/subscription/shipping item | Retrieve that item’s details, then read its notes field/array. |
| Search all notes containing a word or phrase | `BigQueryRunQuery` on `revcent.user.note`. |
| Count notes by day/week/month | `BigQueryRunQuery`. |
| Report note activity by user/agent/support rep | `BigQueryRunQuery`. |
| Analyze customer-service interaction history | `BigQueryRunQuery`, often joined to `customer` or related item tables. |
| Estimate sentiment or support outcomes from note text | `BigQueryRunQuery` with text parsing or downstream analysis. |

---

# Searching Notes With BigQuery

BigQuery can search note text across many notes.

Examples of note searches:

```text
Find notes mentioning refund.
Find notes mentioning callback.
Find notes mentioning chargeback.
Find notes mentioning cancelled.
Find notes mentioning angry or upset customers.
Find notes mentioning replacement shipment.
```

Conceptual SQL:

```sql
SELECT
  id,
  text,
  created_date_unix
FROM `revcent.user.note`
WHERE LOWER(text) LIKE '%refund%'
ORDER BY created_date_unix DESC
LIMIT 100
```

Important:

```text
This query is conceptual.
Use GetBigQueryTables first to confirm the note table field names.
```

---

# Reporting on Note Activity

Because notes can be queried in BigQuery, they can support customer-service and operational reporting.

Possible reports:

```text
Notes created per day.
Notes created per support user.
Customers with the most notes.
Notes by related item type.
Notes containing refund-related terms.
Notes containing cancellation-related terms.
Average number of notes per customer.
Customers with notes over a long support timeframe.
```

Conceptual daily note count:

```sql
SELECT
  DATE(TIMESTAMP_SECONDS(created_date_unix)) AS note_date,
  COUNT(*) AS note_count
FROM `revcent.user.note`
GROUP BY note_date
ORDER BY note_date DESC
```

---

# Customer Service Performance Analysis

The `note` table can help analyze customer-service performance when notes are used consistently.

Possible metrics:

```text
Number of notes created by support user.
Number of customer-service interactions per customer.
Follow-up volume by day/week/month.
Notes involving refunds, chargebacks, cancellations, shipping issues, or callbacks.
Customers requiring repeated support interactions.
Time between first and last note for a customer.
```

These can help answer questions such as:

```text
Which customers have required the most support?
How many support interactions happened this week?
Which support topics are increasing?
Which users are creating the most notes?
How long have certain customers been interacting with customer service?
Are refund/cancellation notes increasing over time?
```

---

# Customer Support Timeframes

BigQuery can help determine how long a customer has been interacting with customer service by looking at the first and last note dates for that customer or related item.

Example business question:

```text
How long has this customer been interacting with customer service?
```

Conceptual approach:

```text
1. Identify the customer.
2. Query notes related to that customer.
3. Find the earliest note date.
4. Find the latest note date.
5. Calculate the difference between first and last note.
```

Conceptual SQL:

```sql
SELECT
  customer_id,
  MIN(TIMESTAMP_SECONDS(created_date_unix)) AS first_note_at,
  MAX(TIMESTAMP_SECONDS(created_date_unix)) AS last_note_at,
  TIMESTAMP_DIFF(
    MAX(TIMESTAMP_SECONDS(created_date_unix)),
    MIN(TIMESTAMP_SECONDS(created_date_unix)),
    DAY
  ) AS support_interaction_days,
  COUNT(*) AS note_count
FROM `revcent.user.note`
WHERE customer_id = 'XXXXXXXXXXXXXXXXXXXX'
GROUP BY customer_id
```

Important:

```text
The actual customer-related field may not be named customer_id.
Use GetBigQueryTables to confirm the note table schema before writing the final query.
```

If the note table uses related item fields instead of `customer_id`, MCP/AI should adapt the query based on the returned schema.

---

# Sentiment and Note Content Parsing

Notes can be searched and parsed to understand support sentiment and customer-service performance.

Examples:

```text
Count notes mentioning angry, upset, frustrated, happy, resolved, refund, cancel, callback, or replacement.
Classify notes into support topics.
Track negative-sentiment note volume over time.
Compare note sentiment before and after policy changes.
Identify customers with repeated negative support notes.
```

Simple keyword-based sentiment concept:

```sql
SELECT
  DATE(TIMESTAMP_SECONDS(created_date_unix)) AS note_date,
  COUNT(*) AS total_notes,
  SUM(IF(REGEXP_CONTAINS(LOWER(text), r'angry|upset|frustrated|mad'), 1, 0)) AS negative_keyword_notes,
  SUM(IF(REGEXP_CONTAINS(LOWER(text), r'happy|resolved|thank'), 1, 0)) AS positive_keyword_notes
FROM `revcent.user.note`
GROUP BY note_date
ORDER BY note_date DESC
```

This is a simple keyword approach, not true sentiment analysis.

For more advanced sentiment analysis, notes can be exported or queried and then processed by an AI system or external analytics pipeline.

---

# Notes for Customer-Service Reporting

Notes can support customer-service reporting when note text is consistent and concise.

Good note-writing practices make BigQuery reporting more useful:

```text
Use consistent wording for common issues.
Keep note text under 255 characters.
Use metadata for structured outcomes.
Use notes for human-readable context.
Avoid internal AI reasoning.
Avoid full transcripts.
```

Examples of report-friendly notes:

```text
Customer requested refund policy clarification.
Customer requested callback tomorrow afternoon.
Customer confirmed corrected shipping address.
Support escalated billing dispute.
Customer plans to retry payment Friday.
```

These are easier to search and categorize than long, inconsistent paragraphs.

---

# Notes + Metadata + BigQuery

For best reporting, use notes and metadata together.

Example:

Note:

```text
Customer requested callback tomorrow afternoon.
```

Metadata:

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

BigQuery can then support:

```text
Searching note text for human-readable context.
Grouping metadata for structured outcomes.
Joining notes with customers/sales/subscriptions for customer-service analysis.
```

Recommended pattern:

```text
Note = concise human-readable explanation.
Metadata = structured reportable/searchable outcome.
BigQuery = cross-record search, reporting, trend analysis, and customer-service metrics.
```

---

# MCP/AI BigQuery Guidance for Notes

When the user asks to search or report on notes:

1. Determine whether they want notes for one item or cross-account analysis.
2. If one item, retrieve item details and read the `notes` array.
3. If searching/reporting across notes, use `BigQueryRunQuery`.
4. Call `GetBigQueryTables` before writing SQL.
5. Reference the notes table as `revcent.user.note` with backticks.
6. Filter by dates when possible to avoid timeouts.
7. Select only needed fields.
8. Use `LIMIT` when exploring.
9. Avoid `COALESCE`.
10. When using `TIMESTAMP_SUB`, only use `INTERVAL` in `DAY`.
11. If parsing note text for sentiment or support performance, treat keyword matching as approximate unless using a dedicated sentiment pipeline.

# CreateNote and Metadata Together

Sometimes the best approach is to create both:

```text
A note for humans.
Metadata for search/reporting/automation.
```

Example:

Note:

```text
Voice call: customer requested callback tomorrow afternoon.
```

Metadata:

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

This allows:

```text
Humans to understand what happened.
Reports to group by outcome.
Automation to trigger on structured metadata.
Search to find relevant records.
```

---

# Example Requests

## Create Customer Support Note

```json
{
  "item_type": "customer",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "text": "Customer asked for refund policy clarification."
}
```

## Create Sale Note

```json
{
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "text": "Sale flagged for support review before refund."
}
```

## Create Shipping Note

```json
{
  "item_type": "shipping",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "text": "Customer confirmed corrected shipping address."
}
```

## Create Subscription Note

```json
{
  "item_type": "subscription",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "text": "Customer wants to keep subscription but update card Friday."
}
```

## Create Subscription Renewal Note

```json
{
  "item_type": "subscription_renewal",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "text": "Renewal failed; customer plans to retry after payday."
}
```

---

# Output Schema

Successful response includes:

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

---

# Validation Checklist

Before calling `CreateNote`:

1. The target `item_type` is known.
2. The target `item_type` is one of the supported enum values.
3. The target `item_id` is known.
4. The `item_id` is 20 characters.
5. The `text` field is present.
6. The note text is 255 characters or fewer.
7. The note is concise and human-readable.
8. The note is not a full transcript, long summary, or internal AI reasoning trace.
9. The note does not contain secrets, credentials, or raw payment data.
10. The note is useful for support, review, automation, or business context.
11. The note summarizes a complete interaction or meaningful stopping point rather than a play-by-play.
12. If structured reporting/search is needed, metadata is considered instead of or in addition to the note.
13. No unknown fields are included.
14. If the user is asking to retrieve notes, do not use `CreateNote`; retrieve the item details and read its `notes` array.
15. If the user is asking to search/report across notes, use `BigQueryRunQuery` against the `note` table after checking schema with `GetBigQueryTables`.

---

# Common Mistakes

## Mistake: Using Notes for Structured Reporting Data

Wrong:

```text
Create many notes like "checkout_page=version_b" and expect clean BigQuery grouping.
```

Better:

```text
Use metadata checkout_page = version_b.
Optionally create a short note if human context is needed.
```

## Mistake: Storing Full Transcripts

Wrong:

```text
Store full AI Voice Agent call transcript in note.
```

Better:

```text
Store transcript in an appropriate transcript/document system.
Create a concise note: "Customer requested callback tomorrow afternoon."
```

## Mistake: Exceeding 255 Characters

Wrong:

```text
Long multi-paragraph summary.
```

Better:

```text
Short, actionable summary under 255 characters.
```

## Mistake: Guessing Item ID

Wrong:

```text
Create note on guessed sale ID.
```

Better:

```text
Search/retrieve the item first, then create the note.
```

---

# Key Takeaways

```text
CreateNote adds a short human-readable note to a specific RevCent item.

To retrieve notes, retrieve the relevant item details, such as `GetCustomer` for customer notes, and read the returned `notes` array.

Notes can also be searched and reported on with BigQueryRunQuery using the `revcent.user.note` table.
```

```text
Note text is limited to 255 characters.
```

```text
Supported item types are sale, customer, product_sale, shipping, subscription, and subscription_renewal.
```

```text
Use notes for concise human context.
Customer interactions should be condensed into a single concise note whenever possible, not documented as play-by-play updates.
Use metadata for structured, searchable, reportable, automatable name/value data.
```

```text
MCP/AI should not use notes for full transcripts, long summaries, secrets, raw payment data, or internal reasoning traces.
```


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