# Idea capture and roundup workflows through MCP

Use Domino’s capture tools when an authorized user asks the connected assistant to remember raw inspiration: text, one public URL, an incomplete idea, or supported media already represented by a current Domino media reference. Use the roundup tools when the source intentionally contains several distinct places or events.

Capture tools perform private Domino writes. They do not contact people, create invitations, make reservations, purchase tickets, or change calendars.

Capture records a **user-originated idea**. When the user asks Domino to propose options instead of supplying a subject, use the current recommendation tools rather than capture. Matching captured source material to a known place or event enriches its structure; it does not make its origin Domino-suggested.

## Before calling a tool

1. Connect with an Agent Access token that includes **Read** and **Draft** abilities.
2. Call MCP `tools/list` on the authenticated connection.
3. Use the exact names and schemas returned for the current token.
4. Generate a stable caller-owned `idempotency_key` for each intentional write.
5. Decide whether the user means one primary subject or an intentional roundup.

The current tool names are:

- `domino_capture_idea` — create one capture or answer its current clarification;
- `domino_get_idea_capture` — read one singular capture;
- `domino_retry_idea_capture` — retry one failed singular capture from its retained source and destination;
- `domino_roundup_capture` — create or mutate one roundup;
- `domino_get_roundup_capture` — read one roundup.

Authenticated `tools/list` remains authoritative if a future catalog uses different names or fields.

## Capture one subject

Call `domino_capture_idea` with at least one source field and a new idempotency key:

```json
{
  "idempotency_key": "capture-20260812-001",
  "raw_text": "Remember this quiet patio restaurant for Andrew",
  "source_url": "https://example.com/restaurant",
  "target_ideas_list_handle": "IDEAS_LIST_HANDLE_FROM_DOMINO"
}
```

Supported current source and context fields can include:

- `raw_text` or `text` for the user’s exact thought;
- `source_url` for one public URL;
- `media_refs` for current supported Domino media references;
- `target_ideas_list_handle` or the current text selector for a destination;
- `target_person_text` for private person context.

Do not discard qualifiers from `raw_text` merely because they also appear structured elsewhere. Preserve the user’s date, venue, neighborhood, activity, person, destination, and descriptive wording.

## Interpret the first result

### `accepted`

The capture was persisted and enrichment is still unconfirmed. Retain:

- `outcome.facts.capture.public_id` or the equivalent returned capture reference;
- the update cursor when returned;
- the next action that points to `domino_get_idea_capture`.

Do not call capture again. Poll the existing operation.

### `needs_input`

Present the exact returned question. Do not turn an ambiguous URL slug, filename, city, date, or venue into a guess.

### `failed`

Present the user-safe error and supported recovery. If the code says the source is an intentional roundup, switch to the roundup workflow with a new idempotency key instead of forcing it through singular capture.

If the outcome includes `domino_retry_idea_capture`, retain the exact application-owned `capture_public_id`, `expected_state_version`, and `optional_input`. Its `execution_policy: on_user_request` means it is available but must not run until the user asks to retry.

## Poll a singular capture

Call `domino_get_idea_capture` with the returned public identifier:

```json
{
  "capture_public_id": "CAPTURE_PUBLIC_ID_FROM_DOMINO",
  "after_cursor": 12
}
```

Omit `after_cursor` on the first read. On later reads, pass only the newest cursor Domino returned. Do not fabricate a polling interval; follow the client or returned next-action behavior and avoid rapid repeated reads.

Continue while status is `accepted`. Treat `needs_input`, `failed`, and `completed` according to the typed outcome.

## Answer a singular clarification

When `domino_get_idea_capture` returns `needs_input`, retain its exact typed next action and ask the user the exact question. Then call `domino_capture_idea` once with:

```json
{
  "idempotency_key": "capture-20260812-clarification-001",
  "capture_public_id": "CAPTURE_PUBLIC_ID_FROM_DOMINO",
  "clarification_answer": "The Lula Cafe in Chicago on Kedzie.",
  "expected_state_version": 1
}
```

Use a new idempotency key because this is new intentional input. Keep the protected capture reference exact and supply only the requested `clarification_answer`; do not replay the original source as a new capture.

The clarification write can return `accepted`; resume polling the same capture identifier until terminal state.

## Retry a failed singular capture

When the user asks to retry the failed work, call the returned tool with a new idempotency key:

```json
{
  "idempotency_key": "capture-20260812-retry-001",
  "capture_public_id": "CAPTURE_PUBLIC_ID_FROM_DOMINO",
  "expected_state_version": 1,
  "additional_detail": "The place is Ping Tom Memorial Park in Chicago."
}
```

Do not resend the source or restate the Ideas List. Domino preserves and reauthorizes both. `additional_detail` is optional research evidence; include only newly supplied facts, not retry wording. An accepted result returns the same capture identifier and a new polling action.

## Report singular completion

Report an idea as saved only when `domino_get_idea_capture` returns terminal `completed` and the facts identify the persisted result. Name:

- the saved idea;
- whether it is general, place-backed, or event-backed when useful;
- the actual Ideas List or general-library destination;
- any remaining limitation disclosed by Domino.

`accepted`, a review URL, a candidate, HTTP success, or a confirmed capture-persistence effect does not prove enrichment and final saving completed.

## Capture an intentional roundup

Use `domino_roundup_capture`, not repeated singular calls, for one source containing several requested items.

Create the roundup:

```json
{
  "operation": "create",
  "idempotency_key": "roundup-20260812-001",
  "source_url": "https://example.com/restaurants",
  "source_text": "Save the restaurants in this article for Date Nights",
  "target_ideas_list_handle": "IDEAS_LIST_HANDLE_FROM_DOMINO"
}
```

When the caller already has a verified structured list, `items` can contain two or more entries using the current tool schema. Do not manufacture titles or identifiers to avoid extraction.

Retain the returned:

- roundup `public_id`;
- `current_generation`;
- status and question;
- exact next action;
- item identifiers and cursor when returned.

## Resolve roundup questions

Every mutation after `create` requires:

- the roundup `public_id`;
- the exact latest `expected_generation`;
- a new `idempotency_key`;
- only the fields for the requested operation.

### Choose scope

When status is `awaiting_scope`, present Domino’s choice in user language:

- `all` — add the matching extracted items;
- `general_source` — keep the roundup itself as one general idea;
- `named_items` — use only explicitly named items.

Example:

```json
{
  "operation": "resolve_scope",
  "idempotency_key": "roundup-20260812-scope-001",
  "public_id": "ROUNDUP_PUBLIC_ID_FROM_DOMINO",
  "expected_generation": 0,
  "scope": "all",
  "selection_policy": "curated"
}
```

Use `selection_policy: "save_all"` only when the user explicitly wants every eligible item. Do not infer it merely from the existence of a roundup.

### Assign a destination

When status is `awaiting_destination`, resolve an authorized Ideas List and pass the current opaque handle or supported text selector:

```json
{
  "operation": "assign_destination",
  "idempotency_key": "roundup-20260812-destination-001",
  "public_id": "ROUNDUP_PUBLIC_ID_FROM_DOMINO",
  "expected_generation": 1,
  "target_ideas_list_handle": "IDEAS_LIST_HANDLE_FROM_DOMINO"
}
```

Never pass an internal numeric list ID or invent a handle.

### Select returned items

When Domino offers item selection, use only the exact selectable identifiers returned by the current roundup state:

```json
{
  "operation": "select_items",
  "idempotency_key": "roundup-20260812-items-001",
  "public_id": "ROUNDUP_PUBLIC_ID_FROM_DOMINO",
  "expected_generation": 2,
  "selected_items": ["ITEM_REFERENCE_1", "ITEM_REFERENCE_2"]
}
```

Do not retype labels as identifiers unless the current tool schema explicitly says to do so.

## Poll and recover a roundup

Read current state with:

```json
{
  "public_id": "ROUNDUP_PUBLIC_ID_FROM_DOMINO",
  "after_cursor": 8
}
```

Use `domino_get_roundup_capture` for polling; reads do not need idempotency keys. Continue through `ready` or `processing` as directed.

For unresolved valid work, call `domino_roundup_capture` with `operation: "retry"`, the latest generation, and a new idempotency key. To close the operation, use `operation: "archive"` under the same generation rule.

If Domino returns `stale_generation`, do not retry the mutation unchanged. Read the roundup again, present any changed state, and use its new generation only after the user’s intent still applies.

## Report roundup completion

Terminal completion must be reported item by item or by returned groups. Distinguish:

- added or saved;
- already seen or reused;
- other options not selected;
- unresolved or needs review;
- omitted because of a documented limit;
- failed.

Never say “all saved” from an accepted mutation or because one child succeeded.

## Media references

`media_refs` are opaque references created by a current supported Domino media-ingress flow. They are not local file paths, arbitrary URLs, base64 data, filenames, or guessed identifiers.

If the MCP client has no supported way to obtain a current media reference:

- capture a public source URL or text instead;
- ask the user to use **Create → Create idea → Add screenshot** on the web; or
- use the supported SMS/MMS capture path.

Never place private media or credentials in a public URL merely to make them callable.

## MCP safety checklist

- Use one new idempotency key for each intentional changed write.
- Replay the same key only with byte-equivalent intended input.
- Preserve returned capture and roundup references exactly.
- Poll the existing operation instead of resubmitting it.
- Follow `needs_input` questions and generation changes rather than guessing.
- Treat only terminal typed state and confirmed persisted facts as authority for completion claims.
- Never expose raw handles, public IDs, cursors, or JSON to an ordinary user unless they ask for debugging output.