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_task

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.

create_tasks

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 (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)

daily_review

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

delete_task

Fetch 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).

fetch

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.

get_agenda

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

get_agent_instructions

List 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_agents

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_assignments

List 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_calendars

List 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_contacts

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_projects

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_tags

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

list_tasks

Post a message in a project's chat on the user's behalf; every other member of the project (owner, co-owners, followers) is notified. This is the project-level thread, not a comment on one task (use add_comment for that). project_id from list_projects/search. body is the message text (1 to 5000 characters). Link a task as [title](task:<uuid>) — task rows carry a ready-made 'link'. Requires the su.assign permission.

add_project_comment

Read a project's chat — the project-level discussion thread shared by everyone in the project (NOT the comments on its individual tasks; those come with fetch on a task). Newest first, with cursor pagination (limit default 20, max 50). project_id from list_projects/search. Use this to catch the user up on what the team said, or before replying with add_project_comment.

list_project_comments

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.

remove_follower

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.

remove_from_google_calendar

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.

remove_tags_from_task

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.

respond_to_assignment

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.

schedule_task

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.

search

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_checklist_item

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_project_status

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_task_priority

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.

set_task_status

As 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_agent_scope

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.

task_stats

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.

unschedule_task

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.

update_task

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

wait_for_reply