Bulk Contact Tools

The get_bulk_contact_memory and get_bulk_contact_messages tools let the assistant load data for many contacts at once instead of making per-contact calls. For a 50-contact batch, this replaces ~100 sequential tool calls with 2.

Tool Summary

Tool	Permissions	Direction
get_bulk_contact_memory	Contact:Instance:View + ContactNote:Collection:List	Read-only
get_bulk_contact_messages	Contact:Instance:View + Message:Collection:List	Read-only

get_bulk_contact_memory

Fetch memory notes for up to 50 contacts in one call.

Input

{
  "contact_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ]
}

Parameter	Type	Required	Limit
contact_ids	UUID[]	Yes	Max 50

Output

{
  "results": [
    {
      "contact_id": "550e8400-...",
      "has_memory": true,
      "memory_note": "Prefers texts over calls. Discussed pricing on March 15.",
      "updated_at": "2026-04-02 09:00 UTC"
    },
    {
      "contact_id": "660e8400-...",
      "has_memory": false,
      "memory_note": null,
      "updated_at": null
    }
  ],
  "total": 2
}

get_bulk_contact_messages

Fetch recent messages for up to 50 contacts in one call.

Input

{
  "contact_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ]
}

Parameter	Type	Required	Limit
contact_ids	UUID[]	Yes	Max 50

Output

{
  "results": [
    {
      "contact_id": "550e8400-...",
      "messages": [
        {
          "direction": "outbound",
          "body": "Hi! Following up on our conversation...",
          "sent_at": "2026-04-10 14:30 UTC"
        }
      ]
    }
  ],
  "total": 2
}

Contact List Enrichment

Contact search and filter results now include two inline fields, reducing the need for follow-up tool calls:

Field	Source	Truncated to
memory_snippet	Contact memory note	200 chars
last_message_preview	Most recent message	100 chars

These fields appear in results from search_contacts, get_contacts_by_filter, get_unanswered_contacts, and get_fresh_contacts. Both are permission-gated — memory_snippet requires ContactNote:Collection:List and last_message_preview requires Message:Collection:List.

When to Use What

Scenario	Tool
Quick scan of contacts	Use enriched list results (memory_snippet, last_message_preview)
Full memory for 1 contact	get_contact_memory
Full memory for 5–50 contacts	get_bulk_contact_memory
Full messages for 5–50 contacts	get_bulk_contact_messages
Bulk operation (>5 items)	Combine bulk tools with the Operation Scratchpad