Folders

Find a folder by name, open it, and walk its subfolders. The documents filed in a folder are listed with list_documents folder_id; read, comment on and export them by document_id as usual.

Tool	Scope	Kind
`list_folders`	`documents:read`	read-only

list_folders

Scope: documents:read (step-up) · Kind: read-only · Annotations: readOnlyHint: true, destructiveHint: false, openWorldHint: false

The folders you can open, as the sidebar shows them. With no arguments: your top-level folders by name. query finds folders by name anywhere in the tree, each with its path. folder_id opens one folder: its path, subfolders, sessions (newest activity first; sessions_cursor → call again with it as cursor for more) and how many documents are filed in it. List those documents with list_documents folder_id, then read, comment on or export them by document_id. Subfolders are not expanded: open each with its own folder_id. role is your access (owner | participant | viewer); a viewer can read but not file documents into the folder.

Parameters

Pass at most one of folder_id and query.

string

Open this folder.

string

Words from the folder name. Matches folders at any depth, only the ones you can open.

string

With folder_id: the sessions_cursor from the previous call, for the next page of the folder’s sessions.

number

default:"50"

Folders to return when listing or searching, 1 to 50. Clamped.

Returns

Without folder_id:

object[]

Each {folder_id, name, role, path, can_nest}. path is the folder’s ancestors from the top, each {folder_id, name} (empty at the top level). can_nest says whether it can hold subfolders.

boolean

More folders matched than were returned: narrow the query.

With folder_id:

object

{folder_id, name, description?, role, path, can_nest}.

object[]

Its direct subfolders you can open, same shape as folders. subfolders_truncated is true past 200.

object[]

Up to 50 sessions filed in the folder, newest activity first, each {session_id, title, last_activity_at}. sessions_cursor is a string when more exist.

number

Documents and pages filed directly in the folder, counted up to 50; artifact_count_capped: true means there are more (the text says 50+).

Permissions and side effects

You see a folder when you could open it in the app: you were added to it or to a folder above it. Reading changes nothing.

Errors

Message	Cause
`Folder not found`	No such folder, or you can’t open it — the same answer either way.
`Pass either folder_id or query, not both`	Both were sent.
`cursor pages a folder's sessions: pass it with folder_id`	`cursor` without `folder_id`.

Example

Review a folder end to end, without a browser:

{ "name": "list_folders", "arguments": { "query": "Customer research" } }
{ "name": "list_folders", "arguments": { "folder_id": "<folder_id>" } }
{ "name": "list_documents", "arguments": { "folder_id": "<folder_id>" } }
{ "name": "read_document", "arguments": { "document_id": "<document_id>" } }

Get started

Use it

Reference

list_folders

Parameters

Returns

Permissions and side effects

Errors

Example

​list_folders

​Parameters

​Returns

​Permissions and side effects

​Errors

​Example

list_folders

Parameters

Returns

Permissions and side effects

Errors

Example