get_audio_recording
Fetch the current public transcript and metadata for a single audio recording by ID.
When to use:
- You already have an audio recording ID and need its transcript + metadata.
When NOT to use:
- You need note-level discovery or linked recording IDs (`get_note`).
list_collections
List collections visible to the authenticated caller with cursor pagination.
Results are ordered by `order_by` and return `next_page` when additional rows are available.
For relevance-ranked retrieval by query, use `search_collections`.
When to use:
- You need deterministic cursor pagination for collections.
- You are iterating through all accessible collections page by page.
When NOT to use:
- You need relevance-ranked retrieval from open-ended text (`search_collections`).
create_collection
Create a collection with optional caller-provided ID and timestamps.
If `id` already exists, the request behaves as an upsert for that collection ID.
Use collection membership endpoints to add or remove notes from collections.
When to use:
- You are creating a new collection.
- You need idempotent upsert behavior with caller-provided IDs.
When NOT to use:
- You only need membership changes between existing notes and collections (`add_note_to_collection` or `remove_note_from_collection`).
search_collections
Search collections using free-text relevance matching.
Returns a bounded relevance-ranked result set and does not return `next_page`.
For deterministic chronological pagination, use `list_collections`.
When to use:
- You need relevance-ranked retrieval for collection lookup.
When NOT to use:
- You need deterministic chronological pagination (`list_collections`).
get_collection
Fetch metadata for a single collection by ID.
This endpoint returns collection metadata only, not a note list for that collection.
For discovery flows, use `list_collections` or `search_collections`.
When to use:
- You already have a collection ID and need canonical metadata.
When NOT to use:
- You need collection discovery without known IDs (`list_collections` or `search_collections`).
update_collection
Update metadata for a collection by ID.
Use this tool to rename a collection by setting `title`.
This endpoint updates only provided fields (`title`, `description`) and leaves omitted fields unchanged.
For read-only retrieval, use `get_collection`.
When to use:
- You need to rename a collection by updating its title.
- You need to update title and/or description for an existing collection ID.
- You need to preserve a collection while correcting metadata.
When NOT to use:
- You need to create a new collection (`create_collection`).
- You only need note membership changes (`add_note_to_collection` or `remove_note_from_collection`).
delete_collection
Permanently delete a collection.
Hard-deleting removes the collection resource itself.
For membership-only changes, use note add/remove collection endpoints.
When to use:
- You need irreversible hard-delete behavior for a collection resource.
When NOT to use:
- You only need note membership changes in a collection (`add_note_to_collection` or `remove_note_from_collection`).
add_note_to_collection
Add an existing note to an existing collection.
This operation only creates the membership link and does not modify note or collection content.
Use create endpoints to create notes or collections.
When to use:
- You need to link an existing note to an existing collection.
When NOT to use:
- You need to create notes or collections first (`create_note` or `create_collection`).
remove_note_from_collection
Remove a note from a collection while keeping both resources.
This operation only removes the membership link between IDs.
Use `trash_note` to remove a note from active notes, or `delete_collection` to remove a collection resource.
When to use:
- You need to unlink a note from a collection while keeping both resources.
When NOT to use:
- You need to remove the note from active notes (`trash_note`) or delete the collection resource (`delete_collection`).
list_notes
List notes visible to the authenticated caller with cursor pagination.
When multiple `contains_*` fields are true, a note may match any of them.
Results are ordered by `order_by` and return `next_page` when additional rows are available.
For relevance-ranked retrieval by query, use `search_notes`.
When to use:
- You need deterministic cursor pagination ordered by `updated_at` or `created_at`.
- You are iterating through all accessible notes page by page.
When NOT to use:
- You need relevance-ranked retrieval from open-ended text (`search_notes`).
create_note
Create a note with optional caller-provided ID, timestamps, and collection links.
If `id` already exists, the request behaves as an upsert for that note ID.
The first line of `content` becomes the note title.
When to use:
- You are creating a new note.
- You need idempotent upsert behavior with caller-provided IDs.
When NOT to use:
- You need to overwrite a known existing note by ID (`update_note`).
- You only need to change note/collection membership (`add_note_to_collection` or `remove_note_from_collection`).
search_notes
Search notes using a required free-text query and structured filters.
When multiple `filter_by_contains_*` fields are true, a note may match any of them.
Returns note results from a bounded search snapshot with deterministic offset pagination.
Query-based searches are relevance-ranked within the bounded search snapshot window.
Reuse the returned `snapshot_id` when requesting later pages.
The returned `total` reflects the bounded search snapshot, capped by the 100-result search window.
For deterministic chronological pagination across all accessible notes, use `list_notes`.
When to use:
- You need relevance-ranked retrieval from a natural-language or keyword query.
- You need query + filter retrieval instead of full feed traversal.
When NOT to use:
- You need deterministic chronological pagination (`list_notes`).
get_note
Fetch the full current state of a single note by ID.
For discovery flows, use `list_notes` or `search_notes`.
When to use:
- You already have a note ID and need canonical content + metadata.
When NOT to use:
- You need note discovery without known IDs (`list_notes` or `search_notes`).
update_note
Submit a complete markdown body for a note and optionally set `updated_at`.
Send the full desired body in `content` (not a partial markdown patch).
The first line of `content` becomes the updated title.
When to use:
- You need full-body replacement for an existing note ID.
When NOT to use:
- You need partial patch semantics (not supported).
- You need create/upsert-by-ID behavior (`create_note`).
trash_note
Soft-delete a note by moving it to trash.
Trashed notes can be restored via `restore_note`.
When to use:
- You need reversible removal from active notes.
restore_note
Restore a previously trashed note to the active note set.
This only reverses soft-delete lifecycle state.
When to use:
- You need to undo a prior trash operation.
When NOT to use:
- The note is already active and does not need restoration.