add_checklist_items
ChatGPTAppend checklist items to a task. task_id from search/list_tasks. items is a list of 1 to 20 non-empty strings (each <=500 chars), appended after any existing items in order. Also accepts an 'occurrence:<series>:<date>' id from get_agenda — that edits ONLY that day of a recurring series, never the series itself.
add_follower
ChatGPTAdd one of the user's contacts as a follower on a task, giving them read+comment visibility; the contact is notified. Two-step: call first WITHOUT confirm to preview, then again with confirm=true to apply. Only the task's owner or current assignee can add followers, and the contact must have a Simply-Useful account (has_linked_user in list_contacts). task_id/contact_id from search and list_contacts. As an agent (agent_id) without auto-approve it only PROPOSES it. Requires su.assign.
add_tags_to_task
ChatGPTPut one or more tags on any task the user can edit, shared ones included (1-10 per call). tags takes NAMES or ids from list_tags. A name means, in order: a tag of the task's PROJECT, then the user's own, then a built-in — and a name matching none of those is CREATED as their own, so call list_tags first and reuse their words. On someone else's task the user's own tags are PRIVATE — nobody else sees them. task_id from search/list_tasks, or an 'occurrence:<series>:<date>' id from get_agenda (that day only).
add_to_google_calendar
ChatGPTPut a task on the user's Google Calendar (needs a connected calendar). The task must already have an upcoming schedule (schedule_task first); the event mirrors it. calendar_id from list_calendars picks the calendar (default: the user's default). Owner-only; not for recurring tasks. On a NEW task awaiting the user's approval it is recorded and the event is created when they approve. Idempotent.
archive_task
ChatGPTArchive a task (hide it from active lists). task_id from search/list_tasks. Pass unarchive=true to restore it instead.
assign_task
ChatGPTAssign a task to one of the user's contacts; the contact is notified. Two-step: call first WITHOUT confirm to preview who will be notified, then again with confirm=true to actually assign and notify. task_id from search/list_tasks; contact_id from list_contacts — ANY active contact works; an external (non-app) contact gets an invitation link. Recurring tasks are refused when the server has recurring collaboration off. Requires the su.assign permission and explicit user confirmation on every call.
bulk_edit_tasks
ChatGPTApply ONE action to MANY tasks in a single call (1-100 task_ids). action: archive | unarchive | set_status (value todo/deferred/done) | set_priority (value default/medium/low/high) | add_tag / remove_tag (value = ONE tag name or id; add_tag creates a name list_tags doesn't have) | delete. delete is two-step: call without confirm to preview (count + first 10 titles, no change), then confirm=true. Per-item outcome {index, id, outcome: ok|not_found}. Prefer this over repeated single-task calls.
create_meeting
ChatGPTSet up an in-app meeting with a Google Meet link and invite contacts (contact_ids from list_contacts); they are notified once the link is ready. Two-step: call WITHOUT confirm to preview, then confirm=true. Impossible without Google Calendar connected. calendar_id from list_calendars; with several calendars ask the user which (an agent may use a default they told it). An agent (agent_id) without auto-approve only PROPOSES it; the user approves in the app. Requires su.assign.
create_project
ChatGPTCreate a project (a container for tasks). Required: title (<=255). Optional: description (plain text, <=50k), status (in_progress — the default — completed, or archived; only pass one for a project the user says is already finished or put away). A color is assigned automatically. Returns the created project with its id.
create_tag
ChatGPTCreate a tag (a label the user puts on tasks). Required: name (<=100 chars). Optional: project (id or title) makes it a PROJECT tag everyone in that project can use — only its owner or a co-owner may; without it the tag is the user's own. Call list_tags FIRST and reuse an existing tag where one fits: a name that already exists in the same place is returned unchanged, and the 'created' flag says which happened. The color is assigned automatically.
create_task
ChatGPTCreate a task or note. type 'task' (default) or 'note'. title <=130. Optional: description (plain text auto-formatted OR limited HTML, see the server instructions; <=50k), priority (default/medium/low/high), deadline (ISO date/datetime), project_id, checklist_items (<=20, each <=500), tags (<=10), schedule_start (ISO datetime or date) + schedule_duration_minutes (default 60) to schedule it. If the request implies a date/time ('Friday afternoon'), ALWAYS set schedule_start. Returns the new item's id.
create_tasks
ChatGPTCreate MANY tasks/notes in one call (1-50). items is a list of objects with the same fields as create_task (title required; type/priority/deadline/project_id/checklist_items/tags/schedule_start/schedule_duration_minutes optional; schedule items with temporal phrasing). atomic=true (default) = all-or-nothing (one bad item aborts all, error names its index); atomic=false = per-item results. Returns per-item {index, id, title} (or {index, error}) plus created_count. Prefer this over repeated create_task calls.
daily_review
ChatGPTReview a whole day in ONE call — use for 'plan my day' / 'what should I focus on' instead of chaining get_agenda + list_tasks + list_assignments. For that day (default today, their tz) returns: agenda (scheduled tasks, events, recurring days), overdue (deadline OR last session slipped before the day), due_today (minus what the agenda shows), and assignments awaiting either side. Archived projects' work is left out. Empty sections are omitted; summary carries full totals. limit caps each section (10, max 50)
delete_task
ChatGPTDelete a task. Two-step: call first WITHOUT confirm to get a preview of what will be deleted, then call again with confirm=true to actually delete it. task_id from search/list_tasks. Deleting a recurring-series master task ends its whole series (the preview says so).
fetch
ChatGPTFetch full details for one task, note, meeting or project by its id ('task:'/'note:'/'meeting:'/'project:<uuid>' from search/list_*, or a bare uuid). Returns id, title, a human-readable text rendering (status, priority, deadline, schedule, project, checklist with item ids, recent comments), a deep-link url and a metadata dict (checklist as {id, title, done}; timestamps ISO 8601, user's tz).
get_agenda
ChatGPTGet the user's plan for one day (default today, their timezone). Returns an ordered timeline of scheduled tasks and owned calendar events overlapping that local day, each with an ISO 8601 'start' (all-day items use 'YYYY-MM-DD'), plus a short summary. An archived project's tasks and repeats never appear. Pass date as YYYY-MM-DD for another day.
get_agent_instructions
ChatGPTYour instructions as one of the user's agents. Call it FIRST on every run with your agent id and do exactly what it returns — it is the current version of your job, so never rely on a copy from an earlier run. A paused agent is refused: stop the run.
list_agents
ChatGPTList the user's agents (personas like 'Marty - Your personal assistant' that work through you): each agent's id ('agent:<uuid>'), name, role, status (active/paused), workspace project id and when it last ran. Use it to recover the agent_id to pass on writes and the workspace project the agent works from — list_projects hides workspaces.
list_assignments
ChatGPTList EXISTING task assignments — never a way to find a person: to look up a contact (e.g. to assign a task), use list_contacts. role='received' (default) shows tasks others assigned TO the user — status pending/pending_permission means it's awaiting the user's accept/decline (use respond_to_assignment); role='given' shows tasks the user assigned to others. Optional statuses filter (pending, pending_permission, accepted, declined, done, revoked). Returns total + cursor pagination.
list_calendars
ChatGPTList the Google calendars the user can add tasks to (name, account, colour, which one is the default) — the calendar_id values add_to_google_calendar accepts. Reports calendar_not_connected when the user has not connected Google Calendar.
list_contacts
ChatGPTList the user's contacts, cursor-paginated (default 20, max 50). Each row has id, display name (the user's own label), status, whether the contact is a linked Simply Useful user and, when the linked user's profile name differs from the label, profile_name — the user may call the person by either, so match both. Never returns email or phone numbers.
list_projects
ChatGPTList the user's projects (owned and shared with them), cursor-paginated (default 20, max 50). BY DEFAULT only projects still IN PROGRESS — pass status='completed'|'archived' for those, or status='all' for every one. Each row has id (project:<uuid>), title, icon, status (in_progress/completed/archived), open/done task counts, and is_archived on archived rows. Falsey/empty fields are omitted. Change a status with set_project_status.
list_tags
ChatGPTList the tags the user can put on tasks, cursor-paginated (default 20, max 50), ordered built-in, then the user's own, then each project's (shared with everyone in that project). Each row has id (tag:<uuid>), name, scope (builtin/personal/project), project name and task_count. ALWAYS call this before tagging and reuse a tag that already means what you want — the tag tools CREATE any name they don't recognise, so an invented variant becomes a real second tag in the user's list.
list_tasks
ChatGPTList/filter the user's tasks. Filters: status OR statuses (todo/deferred/done), project_id, priority, title_exact, title_contains, series_id, has_schedule, has_deadline, tags (names/ids, ANY-of), due_before/due_after (YYYY-MM-DD), overdue=true (deadline OR last session before today, the apps' Overdue), include_archived. order_by: created_at/updated_at/deadline/title/priority ('-' reverses). fields='detail' adds description + counts. An ARCHIVED project's rows need its project_id. Cursor-paged (50, max 200).
remove_follower
ChatGPTRemove a follower from a task. Pass contact_id to remove that contact (allowed for the task's owner or current assignee), or omit contact_id to stop following a task someone shared with the user. The removed follower loses access to the task; no notification is sent. task_id from search/list_tasks. Requires the su.assign permission.
remove_from_google_calendar
ChatGPTTake a task off the user's Google Calendar (deletes the linked calendar event; the task itself and its schedule are NOT changed). Owner-only. task_id from search/list_tasks. Idempotent — removing a task that isn't on the calendar reports there was nothing to remove.
remove_tags_from_task
ChatGPTTake one or more tags off any task the user can edit (1-10 per call), leaving the tags themselves intact for other tasks. tags takes names or ids from list_tags; a name resolves against the task's project first, then the user's own tags, then the built-ins, and one that matches nothing is reported, never created. Another person's own tags on a shared task are invisible to the user, so those cannot be removed. task_id from search/list_tasks, or an 'occurrence:<series>:<date>' id from get_agenda.
respond_to_assignment
ChatGPTAccept or decline a task assignment the user received; the assigner is notified. assignment_id from list_assignments (a task id also works). action='accept' applies immediately to a pending assignment (also approves a pending collaboration request); an assignment already marked done can't be re-accepted — reopen via set_task_status instead. action='decline' is two-step: preview WITHOUT confirm, then confirm=true — declining is final and removes the task from the user's list. Requires su.assign.
schedule_task
ChatGPTSchedule a task (replaces its one-off schedule). task_id from search/list_tasks; start is an ISO datetime (or date for all-day) in the user's timezone; optional duration_minutes (1-10080). An 'occurrence:<series>:<date>' id from get_agenda moves ONLY that day — the series rule is unchanged. recurrence (daily/weekly/monthly) makes a plain task repeat from start (weekly on its weekday, monthly on its day); owner-only. recurrence_end_date (YYYY-MM-DD) = last day; omit to repeat forever.
search
ChatGPTSearch the user's tasks, notes and projects by keyword (case-insensitive substring over titles and descriptions). Returns matches, each with a prefixed id (task:/note:/project:), title and deep-link url. Pass a returned id to fetch for full details. An archived project's tasks are hidden (the project itself still matches). Default 20 results, max 50.
set_agent_scope
ChatGPTAs one of the user's agents, change YOUR OWN scope — only when the user told you to in the chat ("also watch project X", "stick to my personal tasks", "only your own work"). Pass the COMPLETE new scope: scope all | personal | projects | own, and for projects the full list of project ids to keep (plus include_no_project for tasks with no project). It persists across runs and the app shows it under the agent's details.
set_checklist_item
ChatGPTToggle, rename, or remove ONE checklist item. task_id from search/list_tasks; item_id from fetch (its detail lists checklist items as {id, title, done}). Pass EXACTLY ONE of: done (true/false to set completion), title (rename, <=500 chars), or remove=true (delete the item). Returns the updated task. Also accepts an 'occurrence:<series>:<date>' id from get_agenda — that edits ONLY that day of a recurring series, never the series itself.
set_project_status
ChatGPTSet a project's status: in_progress (active), completed (finished, still visible), or archived (put away — the user's apps hide it AND its tasks). project_id from list_projects/search. The user may set any status on their own project; on someone else's they can move it between in_progress and completed only if they are a co-owner. Completing a project does NOT close its open tasks — the result says how many are still open, so offer to handle them.
set_task_priority
ChatGPTSet a task's priority. task_id from search/list_tasks. priority is one of default, medium, low, high. Also accepts an 'occurrence:<series>:<date>' id from get_agenda — that edits ONLY that day of a recurring series, never the series itself.
set_task_status
ChatGPTSet a task's status. task_id from search/list_tasks. status is one of todo, deferred, done. Marking done stamps completion and updates any linked assignment; reopening reverses it. Also accepts an 'occurrence:<series>:<date>' id from get_agenda; on a series someone SHARED with you only done/todo work — every other edit is the owner's.
task_stats
ChatGPTSummarise the user's tasks in ONE call (no paging): total, by_status, by_priority, by_project (top 20), duplicate_titles (title+count, top 20), archived_count, with_schedule, with_deadline, series_count (distinct recurring series). Pass include_archived=true to fold archived tasks into the counts. An archived project's tasks are left out of every figure. Use this to count or find duplicates instead of listing everything.
unschedule_task
ChatGPTRemove a task's one-off schedule. task_id from search/list_tasks. No-op if the task isn't scheduled; refuses tasks whose schedule belongs to a recurring series.
update_task
ChatGPTUpdate a task's fields. task_id from search/list_tasks. Only provided fields change: title (<=130), description (plain text auto-formatted OR limited HTML: p, br, b/strong, i/em, u, a, ul/ol/li, h1-h3; <=50k; '' clears it), priority (default/medium/low/high), deadline (ISO date/datetime). clear_deadline / clear_project remove those; project_id moves it to a project. Also accepts an 'occurrence:<series>:<date>' id from get_agenda — that edits ONLY that day of a recurring series, never the series itself.
wait_for_reply
ChatGPTWait up to timeout_seconds (max 25) for the user to answer you in your office chat. Returns as soon as they write, else empty. Use it after a report that asks the user something: call it repeatedly (passing next_since back as since) for your reply window, act on any reply, and end the run quietly when the window passes. Only the user's own messages count, never yours.
