Simply-Useful

Create 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 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.

Review 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 (open tasks due earlier), due_today (minus what the agenda shows), and assignments awaiting either side. An ARCHIVED project's work is left out. Empty sections are omitted; summary carries each full total. limit caps every section (default 10, max 50).

Delete 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 full details for one task, note or project by its id (prefixed 'task:<uuid>'/'note:<uuid>'/'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 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.

List 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 the user's contacts, cursor-paginated (default 20, max 50). Each row has id, display name, status and whether the contact is a linked Simply Useful user. Never returns email or phone numbers.

List 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 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/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), include_archived. order_by: created_at/updated_at/deadline/title/priority ('-' reverses; priority is ranked). fields='detail' adds description + checklist/comment counts. An ARCHIVED project's tasks are hidden unless you pass its project_id. Cursor-paged (default 50, max 200).

Remove 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.

Take 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.

Take 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.

Accept 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 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 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.

Toggle, 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 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 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 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.

Summarise 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.

Remove 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 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.