ofw_sync_messages
Sync OurFamilyWizard messages into a local cache to surface new and unread inbox items without marking them read, while resuming bounded history backfills across calls.
Instructions
Sync messages from OurFamilyWizard into the local cache. Returns counts per folder and a list of unread inbox messages whose bodies were NOT fetched (to avoid mark-as-read on OFW). Call ofw_get_message(id) on those to read them. EVERY call re-checks the newest page first, so new messages are picked up promptly even while an old-history backfill is still running; only then does it spend what is left of its budget advancing that backfill. Pass deep:true to walk all OFW pages instead of stopping at the first all-cached page (use to backfill suspected gaps). Sync is BOUNDED and RESUMABLE: on hosted deployments a per-call OFW-request budget (env OFW_SYNC_MAX_REQUESTS, or the maxRequests argument) caps how far one call walks; when the budget is hit the response reports done:false with a note — call again with the SAME arguments to resume. done:false means older history is still being backfilled; it does NOT mean recent messages are missing. Local installs are unbounded by default (done is always true). On a server-configured no-read day (OFW_READ_DAYS / OFW_NO_READ_DAYS) no inbox or sent message body is downloaded at all — new messages are cached from the list (sender, date, subject) and the response carries bodiesWithheld:true; the first sync on a reading day fills in those bodies, except unread inbox ones.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| deep | No | If true, walk every OFW page until empty regardless of cache state. Use to backfill gaps. Default false. | |
| folders | No | Folders to sync (default: all three). Must be non-empty if given — an empty list would sync nothing while reporting success. | |
| maxRequests | No | Maximum OFW requests this single call may make before pausing. When hit, the response reports done:false — call again with the same arguments to continue. Omit to use the server default (OFW_SYNC_MAX_REQUESTS, or unbounded on local installs). | |
| confirmToken | No | ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation. | |
| fetchUnreadBodies | No | If true, also fetch bodies for unread inbox messages — which marks each one READ on OurFamilyWizard and stamps a co-parent-visible "First Viewed" time that cannot be undone. Defaults to the OFW_FETCH_UNREAD_BODIES env var (false unless set). Applies only when the inbox is among the folders synced. Refused outright when OFW_ALLOW_MARK_READ=false or on a no-read day (the response's unreadBodies says which). When the server runs with OFW_CONFIRM_MARK_READ=true, the sync runs WITHOUT marking anything read and then asks the user to confirm opening the listed unread messages (newest 25 per call): a confirmation prompt where the client supports one; otherwise it returns that list plus a confirmToken, and only a repeat call with that token opens them. Show the user the list and wait for their yes. |