Context-gathering tools

Read-only tools an assistant uses to understand your vault before acting. None of these mutate anything. Inputs marked optional may be omitted.

Review fields

Each element of get_weekly_context.projects:

{"slug": "harbour-survey", "held_by": "the harbour office", "counts": false,
 "waiting_on_empty": false, "core_question": null, "changed_this_week": true,
 "focus_days_while_held": 2}

The weekly review asks the person’s own projects whether they moved, and a handed-off project that changed this week what came back and what awaits the person’s decision. get_monthly_context’s parked and stuck entries carry held_by, counts and waiting_on_empty with the same meanings, so the monthly review tells a project shelved for someday from one someone else has.

Slots and counts

slots, on list_projects, get_orientation and get_monthly_context:

{"active": 3, "counted": 2, "cap": 5}

Each list_projects row (active, parked and closed) and the get_project_context payload carry counts, with the meaning in the review fields, and their frontmatter carries held_by exactly as written, since it is the frontmatter view: a sentinel comes through as its text there, while the summaries’ held_by reads null for it. Branch on counts, never on the holder’s name. list_projects stays a listing that reads no map body, so its rows carry no waiting_on_empty; the orientation projects carry it.

Focus fields

current_focus, the focus field of get_orientation and the focus field every focus-carrying write result share one shape:

{"project": "surrogate-model", "action": "Draft the methods section (deep)",
 "started": "08:50", "date": "2026-10-04", "carried": false,
 "origin": {"started_at": "2026-10-03T14:05"}}

null means nothing is open, wherever it appears.

last_paused, on get_orientation’s projects and on get_project_context:

{"project": "surrogate-model", "action": "Draft the methods section (deep)",
 "title": "Draft the methods section", "at": "2026-10-04T11:13", "date": "2026-10-04",
 "next": "pick up at \"Prior approaches\"", "reason": "lunch"}

It is the project’s most recent pause that no later started, resumed, completion, drop or promotion of the same action followed, looked for in the last paused_lookback_days days; next and reason are null when the pause had none. Quote next back to the person when they pick the project up. The server instructions tell an agent how to use the focus; see Write tools.

Notes

• Dates are YYYY-MM-DD. Week-scoped tools accept any day within the target ISO week; month-scoped tools accept any day within the target calendar month.
• search_notes returns the same hit shape as the CLI: path, note_type, title, snippet, score. See JSON output.
• completed_actions (weekly and monthly) covers both forms an action takes. One with its own note carries slug and path alongside source: "note"; an inline bullet — the default form, and so the common case — carries source: "bullet" with both null. A client must expect null there. A completion that has both a note and a log line is listed once, and dropped actions never appear. The list is read from the daily notes directly rather than from the capped logs field, so a completion early in a busy week is not lost to that cap.
• read_note reads any note, of any type. content_hash is the hash of the bytes just read, the value to hand back as expected_hash when revising the note, so a change made in between is detected rather than overwritten. backlinks comes from the index, which every cuaderno write updates; a link made by editing a file elsewhere appears once the index next reconciles. A slug several notes share is refused with code ambiguous_slug and the candidates’ paths in details.candidates; a reference matching nothing is refused with code not_found. headings lists every heading in the body with inline markup stripped, the form revise_note’s section takes. To follow a heading link such as a concept’s origin ([[journal/2026/daily/2026-09-02#Woodbury identity]]), pass the part before the # and find the entry under that heading: the whole link, anchor included, is refused as not_found. When note was a former name of a renamed note, the payload adds found_by_former_name (the name typed) and path shows where the note is now: use the current slug from then on.
• These pair naturally with the write tools: read context, propose an action, then write it.