Ephemerals Tools

Manage transient cached data. List active datasets, inspect contents, label entries, and extend TTL.

Ephemerals provide a managed view over your active cache entries in ResultCache. When tool calls produce data, results are cached with a cache_ref that you can use with frame tools, prism.paginate, or data tools. Ephemerals tools let you see what’s cached, preview it, and keep it alive longer.

When items expire from the cache, they simply vanish from the list. This is the feature — ephemerals are working memory, not permanent storage. To keep something permanently, use deliverables.register to promote it.

ephemerals.list@1

List all active ephemeral (cached) datasets for the current user.

Parameters

Example

{
  "name": "data-grout@1/ephemerals.list@1",
  "arguments": {
    "sort": "expiring_soon"
  }
}

Response:

{
  "ephemerals": [
    {
      "cache_ref": "rc_abc123",
      "label": "Overdue invoices (filtered)",
      "source_tool": "quickbooks@1/get-all-invoice-details-list@1",
      "record_count": 142,
      "type": "leaf",
      "created_seconds_ago": 120,
      "expires_in_seconds": 180
    }
  ],
  "total": 1,
  "message": "1 active ephemeral dataset. Use cache_ref with frame tools or prism.paginate."
}

Cost

0 credits — ETS scan only.

ephemerals.inspect@1

Get detailed stats and a preview of a specific cache entry. Automatically extends the entry’s TTL by 10 minutes — inspecting data keeps it alive while you decide what to do with it.

Parameters

Example

{
  "name": "data-grout@1/ephemerals.inspect@1",
  "arguments": {
    "cache_ref": "rc_abc123",
    "preview_rows": 5
  }
}

Response:

{
  "cache_ref": "rc_abc123",
  "type": "leaf",
  "record_count": 142,
  "schema": [
    {"field": "amount", "type": "float"},
    {"field": "customer", "type": "string"},
    {"field": "due_date", "type": "string"}
  ],
  "preview": [
    {"amount": 1500.0, "customer": "Acme Corp", "due_date": "2026-02-01"},
    {"amount": 750.0, "customer": "Widget Inc", "due_date": "2026-01-15"}
  ],
  "expires_in_seconds": 180,
  "created_seconds_ago": 120,
  "source_tool": "quickbooks@1/get-all-invoice-details-list@1",
  "label": "Overdue invoices (filtered)",
  "source_chain": {"type": "leaf"}
}

Cost

0 credits — ETS lookup only.

ephemerals.tag@1

Attach a human-readable label to a cached entry for easier identification. Does not extend TTL.

Parameters

Example

{
  "name": "data-grout@1/ephemerals.tag@1",
  "arguments": {
    "cache_ref": "rc_abc123",
    "label": "Q1 overdue invoices"
  }
}

Cost

0 credits.

ephemerals.extend@1

Extend the TTL of a cache entry to keep it alive longer.

Parameters

Example

{
  "name": "data-grout@1/ephemerals.extend@1",
  "arguments": {
    "cache_ref": "rc_abc123",
    "minutes": 30
  }
}

Cost

0 credits.

When to use which tool