Folder Search

Overview

search_private_folders and search_team_folders find private and team folders by name. Both use case-insensitive substring matching with NFC normalization, so Korean and other CJK text matches reliably.

search_private_folders — Search your private (non-shared) folders.
search_team_folders — Search team (workspace-shared) folders.

Both tools take the same parameters and behave the same way. Both require credentials with user identity (a user-scoped API key or OAuth token) and the mcp:folder:read scope. Pass a workspaceGuid to search another workspace. When to use

Find a specific folder by name when you only remember part of it (e.g., “general” matches “0.General”, “General”, “general-things”).
Enumerate all folders in a workspace (empty keyword returns all, paginated).
Korean character search: keyword="네이버" matches "네이버 모니터링", "0.네이버", etc.

How search works

Case-insensitive substring matching (NFC-normalized for CJK reliability).
Folders sorted by match position (start-of-name ranks higher) then by name length (shorter ranks higher).
Each result includes the folder’s breadcrumb path (e.g., "Engineering > Q1 Planning > Sprint 1").
Empty keyword returns all folders, paginated.
Backward-compatible dual response fields: content (recommended) and notes (legacy alias).

v1 implementation: Each call fetches the folder tree and filters it server-side. The MCP signature stays the same when a backend search endpoint is added.

Parameters

Both search_private_folders and search_team_folders accept identical parameters:

Parameter	Type	Required	Description
`keyword`	string	Optional	Folder-name substring to search (case-insensitive, NFC-normalized). Omit to enumerate all folders.
`cursor`	string	Optional	Pagination cursor from a previous `nextCursor`. Pass this to fetch the next page.
`size`	number	Optional	Results per page (default `30`, max `100`).
`workspaceGuid`	string	Optional	Workspace GUID (from `list_workspaces`). Omit to use the API key’s workspace; pass one to target another.

keyword (optional)

Case-insensitive substring match. The search is normalized using NFC (Canonical Decomposition, followed by Canonical Composition) to handle Korean, Japanese, Chinese, and other CJK text reliably. Empty or omitted keyword returns all folders, paginated. Examples:

"general" matches "0.General", "General", "general-things" (sorted by match position, then name length).
"네이버" matches "네이버 모니터링", "0.네이버", "팀별 > 네이버".

cursor (optional)

Pass the nextCursor from a previous response to fetch the next page. Omit for the first page.

size (optional)

Results per page. Default 30, max 100. Smaller pages return faster; larger pages reduce round-trips.

Response Format

Success Response (search_private_folders)

{
  "content": [
    {
      "folderId": 12345,
      "name": "General",
      "path": "General"
    },
    {
      "folderId": 12346,
      "name": "Q1 Planning",
      "path": "Engineering > Q1 Planning"
    }
  ],
  "notes": [
    {
      "folderId": 12345,
      "name": "General",
      "path": "General"
    },
    {
      "folderId": 12346,
      "name": "Q1 Planning",
      "path": "Engineering > Q1 Planning"
    }
  ],
  "total": 47,
  "totalSize": 2,
  "nextCursor": "30"
}

Field Descriptions:

Field	Type	Description
`content[]`	array	Search results (recommended field).
`content[].folderId`	number	Stable folder identifier.
`content[].name`	string	Folder name (e.g., `"General"`, `"Q1 Planning"`).
`content[].path`	string	Breadcrumb path (e.g., `"Engineering > Q1 Planning > Sprint 1"`), joined with `>`. Top-level folders have `path` equal to `name`.
`notes[]`	array	Legacy alias for `content`. Both arrays contain identical data. Pick whichever your client prefers.
`total`	number	Total number of folders matching the keyword (entire result set, across all pages).
`totalSize`	number	Number of results on this page.
`nextCursor`	string (optional)	Cursor for the next page. Treat it as an opaque string — when there are no more results this field is omitted from the response entirely (not `null`).

The response includes both content (recommended, modern naming) and notes (legacy alias) for backward compatibility. They reference the same array object — pick whichever your code prefers and ignore the other.

Usage Examples

Example 1: search_private_folders — Simple keyword

Request:

{
  "keyword": "general"
}

Returns all private folders matching “general” (case-insensitive), paginated. Response:

{
  "content": [
    {
      "folderId": 100,
      "name": "General",
      "path": "General"
    },
    {
      "folderId": 101,
      "name": "0.General Announcements",
      "path": "General Folder > 0.General Announcements"
    }
  ],
  "total": 2,
  "totalSize": 2
}

(Since there are no more results, the nextCursor field is absent from the response.)

Example 2: search_team_folders — Korean keyword

Request:

{
  "keyword": "네이버"
}

Returns all team folders with “네이버” in the name (NFC-normalized for CJK matching). Response:

{
  "content": [
    {
      "folderId": 200,
      "name": "네이버",
      "path": "파트너십 > 네이버"
    },
    {
      "folderId": 201,
      "name": "네이버 API 모니터링",
      "path": "기술 > 파트너 > 네이버 API 모니터링"
    }
  ],
  "total": 2,
  "totalSize": 2
}

(Since there are no more results, the nextCursor field is absent from the response.)

Example 3: Enumerate all folders (empty keyword)

Request:

{
  "keyword": "",
  "size": 50
}

Returns the first 50 folders (all top-level and nested) in no particular order. Response:

{
  "content": [
    { "folderId": 1, "name": "Engineering", "path": "Engineering" },
    { "folderId": 2, "name": "Q1 Planning", "path": "Engineering > Q1 Planning" },
    { "folderId": 3, "name": "General", "path": "General" }
  ],
  "total": 137,
  "totalSize": 3,
  "nextCursor": "50"
}

Example 4: Pagination

First page (omit cursor):

{
  "keyword": "sprint",
  "size": 20
}

Second page (using nextCursor from first response):

{
  "keyword": "sprint",
  "size": 20,
  "cursor": "20"
}

Sort Order

Results are sorted by match position, then by folder name length (shorter names rank higher at the same match position):

Match position ascending — Folders whose name starts with the keyword rank above folders that contain it later in the name.
- keyword="general" → "General" (position 0) ranks above "0.General" (position 2).
Name length ascending — When match position is tied, shorter names rank higher.
- Both start at position 0 and match “gen”: "General" (7 chars) ranks above "General Announcements" (21 chars).

This ensures the most specific matches surface first.

Best Practices

Pick the tool by folder type, not API key type

search_private_folders searches your private (non-shared) folders; search_team_folders searches team (workspace-shared) folders. Both require credentials with user identity (a user-scoped API key or OAuth token) and the mcp:folder:read scope; choose the tool by folder type. When the workspace has no matching folders, the response is an empty list (not an error).

Target a specific workspace with workspaceGuid

Both tools operate on your API key’s workspace by default. To search folders in another workspace you can access, pass an explicit workspaceGuid obtained from list_workspaces.

For CJK text, rely on NFC normalization

Korean, Japanese, and Chinese text is automatically NFC-normalized server-side. You don’t need to preprocess your keywords — just pass the raw text and the matching engine handles it.Example: keyword="네이버" will match folders with composed or decomposed forms of the same text.

Paginate with nextCursor, not offsets

Always use the nextCursor returned in the previous response. Don’t try to compute offsets yourself — pagination behavior may change in future releases.

Use empty keyword to enumerate all folders

To get a complete list of folders without filtering, omit keyword or pass an empty string. Use size and nextCursor to paginate through the full result set.

Common Errors

Insufficient scope

Solution: Your API key lacks the mcp:folder:read scope. Generate a new key with the correct scopes, or contact your workspace administrator to grant access.

Token Usage

Operation	Tokens
Empty keyword (enumerate all folders)	~200–500
Keyword search	~200–500

Folder search is lightweight — results include only names and paths, not content.

Scope Requirements

Both search_private_folders and search_team_folders require credentials with user identity (a user-scoped API key or OAuth token) and the mcp:folder:read scope. Configure API keys at Tiro Platform API Keys.

Note: The folder write tools (update_folder, move_folder, reorder_folders) were deprecated on 2026-07-20. MCP is currently read-only. See Edit notes and folders for details.

list_notes — Find notes within a specific folder using filter.folderId (no separate “list folders” tool needed).
search_notes — Search notes in a folder with filter.folderId (keyword-required deep search).

Home

Getting Started

API

Voice File

Webhooks

MCP

CLI

Developer Resources

Overview

Parameters

keyword (optional)

cursor (optional)

size (optional)

Response Format

Success Response (search_private_folders)

Usage Examples

Example 1: search_private_folders — Simple keyword

Example 2: search_team_folders — Korean keyword

Example 3: Enumerate all folders (empty keyword)

Sort Order

Best Practices

Common Errors

Insufficient scope

Token Usage

Scope Requirements

​Overview

​Parameters

​keyword (optional)

​cursor (optional)

​size (optional)

​Response Format

​Success Response (search_private_folders)

​Usage Examples

​Example 1: search_private_folders — Simple keyword

​Example 2: search_team_folders — Korean keyword

​Example 3: Enumerate all folders (empty keyword)

​Example 4: Pagination

​Sort Order

​Best Practices

​Common Errors

​Insufficient scope

​Token Usage

​Scope Requirements

​Related Tools

Overview

Parameters

keyword (optional)

cursor (optional)

size (optional)

Response Format

Success Response (search_private_folders)

Usage Examples

Example 1: search_private_folders — Simple keyword

Example 2: search_team_folders — Korean keyword

Example 3: Enumerate all folders (empty keyword)

Example 4: Pagination

Sort Order

Best Practices

Common Errors

Insufficient scope

Token Usage

Scope Requirements

Related Tools