What your agent can do

Once connected, your agent sees a catalog of Kept tools. You never call them by name; you ask in plain words and the agent picks. This is what is in the box.

Read your day

Get today: events, habits, plan, sleep and mood if present. Get what is happening now. Read the daily briefing. List focus sessions. The same tools are how "what's on my plate" gets answered.

Capture and route

Capture a line and let Kept file it, exactly as the app does. Or ask for a routing preview without writing anything, to see how Kept would classify a line before committing.

A day you rule out is never the day kept_capture files, and it never fills the gap with today. When your line rules out a day, as in "Meet Dana Thursday rather than Friday at 3pm", "Meet Dana Friday at 3pm, not Thursday" or "Dentist not 10/23 at 3pm", Kept does not choose a day for you, and an event is not saved: the reply says nothing was saved because the line rules out a day (committed: false, needs: "day") so the agent asks you which day and then creates the event with it. A task from such a line is saved with no day and no repeat, even when it names a time, and the reply says so (day_needed), so "every weekday except Friday stand up notes" never becomes a repeat that includes Friday and "call the plumber at 3pm, not the 1st or 2nd" is not due today. Repeat words with a "no" or "not" that rules out no day still repeat: "every weekday standup, no laptops" is a repeating task, not an event today. An event whose line names no day at all still lands today, as before.

Tasks

List, search, and export tasks; search includes finished ones unless the agent asks otherwise. Create a task with an area, priority, due date, and a why. A task created this way can thread to the goal in its life area when there is exactly one, so an agent's tasks land where the app would file them. Complete, reopen, and update. Add and check steps. Read and add comments. A connection that acts as you can also hold a task out of Top 3 until a date.

A task can also repeat. When you ask for it in so many words ("every Thursday", "every month"), an agent sets the repeat on kept_create_task or kept_update_task, and kept_list_tasks shows it. A repeat set on a task with no date dates it to its first occurrence. Kept makes each next occurrence itself when one is completed, so an agent never creates the future copies. A repeat is placement: a connection acting as you can set it, and an agent can set it only on work it created and holds; an agent asking you to do something leaves it out. kept_capture from a connection acting as you reads repeat words the way Capture in the app does: "water the plants every day" files a task that repeats every day, dated to today, while a line whose repeat words describe something else, such as "cancel the Netflix that bills me every month", files a one-off. When an agent hears a repeat that kept_capture would not read, it sets the repeat explicitly with kept_create_task.

An agent can name an area the way you see it ("Studio Work") or by its key ("studio_work"). Kept stores the area's key either way, so the task lands under that area's filter on iPhone and Mac, and finding tasks by area returns the ones saved under either spelling. An area name Kept doesn't recognize is saved in the words the agent used and still shows up as its own filter.

Notes

Search by keyword or by meaning. Note search and note reads say whether a note is starred. kept_update_note can star or unstar it without adding another tool to the catalog. Read a note in full, including the page it sits under. Create one, update one, move it to a folder, link it to a task. Make a page inside a note (a subpage) with kept_create_subpage, list a page's subpages with kept_list_note_children, and move a note into another page or back to the top level with kept_update_note; a move names the parent the agent last read, so it never undoes a move you made since, and a page can never go inside itself. Read and append today's daily note. Ask what your notes say about a topic, which decisions you made about it, and which notes relate. Read and edit a note's blocks directly. Read a note's automatic connections -- the same small, curated handful of entities Kept surfaces in the app (normally three, never more than five automatic, plus anything you have explicitly kept), each with how confident and how useful Kept judges it -- not the complete internal knowledge graph.

Keep shared-note access explicit

Existing agent connections keep their current shared-note metadata access. These tools cannot read another person's note body, task connections, import details or discussion. See Shared note privacy.

Shared notes

See which notes are shared: the ones people invited you into and your own notes that have other people in them, with each note's title, who shared it, your role, and how many people are in it (kept_list_shared_notes). See who is in one shared note by first name and role, and, on a note you own, which invitations are still open, each address shown masked (kept_list_note_collaborators). Both only read. Your agent never gets the words of a note someone else owns, anyone's account id, or a full email address.

A shared note is edited together in Kept, so an agent cannot rewrite its text: kept_update_note answers _This note is shared. Edit it in Kept._ and changes nothing, while a title, folder, or tag change still goes through. Inviting, removing, and accepting happen in the apps. Until sharing is on for Kept, both tools say collaboration isn't available yet.

Tables

Availability: The table tools join the connection only where Tables is on for your account. Until then they are absent from the tool list, and calling either one answers unknown_tool.

Read a table with kept_table_read (notes:read). Change one with kept_table_edit (notes:write). Both use the note permissions you already granted, and neither needs a new one. An agent reads and changes a table you already have: cells, rows, properties, and saved views. It does not create a table, turn a plain grid into one, or choose which page a row opens as. Those stay in Kept.

Reading a note's blocks (kept_note_blocks_read) shows a table's rows and properties, and which row has a page. Rewriting a note's words with kept_update_note, or editing one of a table's blocks as if it were plain text, cannot flatten a table: the request is refused, the rest of the note can still be edited, and the agent is pointed to the table tools instead. An edit follows the same limits as the apps (Limits).

What an agent sends

These are the arguments the tools accept. The arguments, and each command, refuse a field that is not listed. A property or a view may also carry fields a newer Kept added; send back what you read.

kept_table_read takes:

• note_id (required, a UUID): the note that holds the table.
• table_id (optional): the table's id from a previous read. Leave it out only when the note holds exactly one table. When the note holds more than one, the answer lists them and reads none until you pass table_id.
• view_id (optional): a saved view to apply. Leave it out to use the table's default view.
• cursor (optional, a whole number from 0 to 100,000): pass back the next_cursor you were given. Leave it out for the first page.
• limit (optional, a whole number from 1 to 100): rows in this page. Leave it out for 50.

The answer includes the table's properties (id, name, type, source_digest, and select options when it has them), its saved views, and one page of rows. Every property includes a source_digest. Each cell is the stored value, keyed by property id, so the value just read is the base an edit must send back. Keep passing next_cursor back as cursor while the answer includes one. A table from a newer version of Kept comes back as its plain cells with read_only set.

kept_table_edit takes note_id (a UUID), table_id from that read, one operation_id (a UUID), and commands (from 1 to 25). Generate operation_id once for the change you intend, and send that same id again if you retry. A retry returns the original result and never adds a row twice. Sending that id again with different commands is refused. Commands in one request are one change. A refused request changes nothing at all. The answer names the refused command's index (failed_index).

Do not send client_op_id or block_id. Kept adds both. The command kinds an agent may send:

• table.update carries expected_rev, plus name, default_view_id, or both. One of those two is required.
• table.cell_set carries row_id, property_id, base (the value you read for that cell, or null when it was empty), and value.
• table.row_insert carries row_id, after_row_id (null puts the row first), and props. It may also carry page (a UUID, or null).
• table.row_delete carries row_id.
• table.row_move carries row_id and after_row_id (null moves the row first).
• table.property_insert carries property and after_property_id, and may carry values (a map of row id to stored value).
• table.property_update carries property_id, expected_rev, and patch. When patch changes the type, it also carries expected_source_digest, the source_digest from the property you read. A missing or stale digest is refused as stale_preview, and you read the table again after values change. When patch removes an option rows still use, it also carries option_remap: each removed option id maps to a replacement option id, or null to clear those values.
• table.property_delete carries property_id and expected_rev.
• table.property_move carries property_id, expected_rev, and after_property_id.
• table.view_create carries view (including its id), and may carry after_view_id. Null or left out puts the view first.
• table.view_update carries view_id, expected_rev, and view. This view has no id.
• table.view_delete carries view_id and expected_rev.

A property is id, name, and type, plus options, width, align, and rev when the read included them. A view definition is name, kind, filters, sorts, group_by, visible_property_ids, and property_order.

Stored values use these shapes. Title and text are arrays of runs, like [{"t":"words"}]. A number is a decimal string, like "12.5". Select is an option id. Multi-select is an array of option ids. A date is YYYY-MM-DD. A checkbox is true; null clears it. A link is an http, https, or mailto address.

Property and view commands carry expected_rev from the read. An agent changes a property's type with the source_digest it read. If someone else changed that cell first, the edit is refused as cell_conflict. A refused request, including invalid_view, retype_lossy, stale_preview, and cell_conflict, changes nothing at all. A shared note is refused, and the answer says to edit it in Kept. A table from a newer version of Kept is refused, and the answer says to update Kept.

The kinds an agent does not send are table.create, table.adopt, and table.row_page_set.

Calendar

List calendars and events. Search events by name. Check a window for conflicts. Find free slots that respect your connected calendars and Kept events. Read an event's details and guests. Create an event, update it, move it to another calendar. Inviting a guest or replying to an invitation only stages a confirmation card inside Kept; nothing is emailed until you confirm it in the app.

Habits and goals

List habits and habit groups; complete or uncomplete a habit for a date; create, update, and archive habits; create, rename, reorder, and archive groups. List goals, read one, create one, update it, set declared progress, archive it. Read habit history. Reading a goal gives its target and starting value in the goal's saved unit, with money in whole currency units; it does not include the goal's dated readings.

Memory and profile

Recall what Kept remembers about a topic. Remember a new fact. Forget one, which archives it reversibly. List memories. Read your life areas, name, and time zone.

Health history

Weight trend, sleep range, mood range, habit history, and defined metric series, bounded to a window. These sit behind a separate health:read permission that no one-click preset includes.

Asks from this agent

An agent can list the things it has asked of you, hand a task it created back to you or take it on itself, and withdraw an ask it no longer needs.

Kept's own documentation

Search this guide. An agent that hits a question about how Kept works can look up the answer from the same articles you are reading, where that switch is on for your account.

Cloud Agents jobs

Cloud Agents are not in the Apple 1.8.6 release. iPhone and Mac do not show delegation, agent inboxes, approvals queues, or agent hand-off. Connected MCP agents can still use the job tools below when that rollout is on for the account.

Create a job, read it, list jobs, read a run's events, and submit an approval. These are gated behind their own permissions and are off in every default grant. High-consequence approvals cannot be approved over MCP at all; the app asks you to type them back.

Registered, but not available yet

Kept has registered four Goal Builder tools and one Changes-history tool for schema and catalog review. They are not in the default connection and are not discoverable to an agent yet. Goal Builder stays out until its staged plan is stored durably for the connected account, confirmation reuses the atomic app commit, retries return the same receipt, and Undo cannot resurrect a plan. Changes history stays out until its owner-scoped Activity backend is approved. The registered catalog has 98 names. The production connection max is 93 when Cloud Agents jobs and documentation search are on. Those five names stay undiscoverable until their receipts land. The default connection has 87 tools.

Today keeps its existing tools while the new snapshot and priority-session projection is waiting on its own backend approval. An agent cannot opt into any of these pending paths by adding an argument or asking for a broader permission.

What is deliberately impossible

• No deletes. Nothing in the catalog destroys data. Forget and archive are reversible.
• No emailing on your behalf. Inviting a guest or replying to an invitation stages a confirmation in Kept; the email goes only when you confirm it there. Inviting someone into a note happens only in the apps.
• No flattening a table. An update that would turn a table into plain text, or edit its blocks as plain blocks, is refused. Tables change through the table tools.
• No editing a shared note's words. People edit a shared note together in Kept; an agent can list shared notes and who is in them, nothing more.
• No thinking without Cloud AI. Capture routing, recall, remember, and the day's plan answer with a plain refusal while Cloud AI is off in Settings.
• No identity switching. Every call acts as you, from the token. A tool that is handed a user id ignores it.
• No repeating events over MCP. An agent creates single events; repeating series are made in the app. Repeating tasks are available (see Tasks above).
• No Health rule setup. Apple Health habit rules are configured in the native apps only.
• No staged Goal Builder yet. Goal-plan Markdown, progress entries, milestone completion, and staged goal building remain unavailable until their backend and rollout gates pass.
• No Changes history yet. The registered read tool remains unavailable until its Activity backend is approved.

Next: Permissions and safety.

Shared-note privacy protection adds no agent permission. Existing connections remain limited to shared-note metadata, and cannot read the owner’s separate private note details. Shared text still requires the separately authorized capability described in Shared note privacy.