Folder Search

Overview

Folder search tools (search_user_folders and search_team_folders) provide a unified way to find folders by name within your personal or team folder hierarchy. Both tools use case-insensitive substring matching with NFC normalization, ensuring reliable matching for Korean and other CJK text.

search_user_folders — Search your personal folder structure (requires user-based API key).
search_team_folders — Search your team’s folder structure (requires team API key).

Both tools share the same signature and behavior; the only differences are the API key type required and which folder universe they search. Primary Use Cases:

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.

Key Features:

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 folders (legacy alias).

v1 implementation note: These tools fetch the upstream folder tree once per call and filter server-side. A native backend folder-search endpoint is on the v2 roadmap. When added, the MCP signature stays identical — this is an implementation detail.

Parameters

Both search_user_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`).

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

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

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`.
`folders[]`	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 \| null	Cursor for the next page. `null` when no more results.

The response includes both content (recommended, modern naming) and folders (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_user_folders — Simple keyword

Request:

{
  "keyword": "general"
}

Returns all user 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,
  "nextCursor": null
}

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,
  "nextCursor": null
}

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": "eyJvZmZzZXQ6NTB9"
}

Example 4: Pagination

First page (omit cursor):

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

Second page (using nextCursor from first response):

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

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

Use search_user_folders with user-based API keys

search_user_folders requires a user-based API key. Team-only API keys return a 403 TEAM_REQUIRED error. Create a user API key at Tiro Platform API Keys.

Use search_team_folders with team API keys

search_team_folders requires a team-based API key. User-only API keys return a 403 USER_REQUIRED error. Generate a team API key from the team’s settings page.

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

User API key required

Solution: You called search_user_folders with a team API key. Switch to a user-based API key or use search_team_folders if you need team folders.

Team API key required

Solution: You called search_team_folders with a user-only API key. Switch to a team-based API key.

Insufficient scope

Solution: Your API key lacks the mcp:folders: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_user_folders and search_team_folders require the mcp:folders:read scope. Configure your API key at Tiro Platform API Keys.

Note: The mcp:folders:write scope no longer exists (as of 2026-05-06). All folder write operations were removed. If you have an old API key with mcp:folders:write, it will be ignored — the scope is not used.

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

Get Started

Fundamentals

API Reference

Webhooks

Template Based Documents

MCP Server

External Viewers

Overview

Parameters

keyword (optional)

cursor (optional)

size (optional)

Response Format

Success Response (search_user_folders)

Usage Examples

Example 1: search_user_folders — Simple keyword

Example 2: search_team_folders — Korean keyword

Example 3: Enumerate all folders (empty keyword)

Sort Order

Best Practices

Common Errors

User API key required

Team API key required

Insufficient scope

Token Usage

Scope Requirements

Get Started

Fundamentals

API Reference

Webhooks

Template Based Documents

MCP Server

External Viewers

Documentation Index

​Overview

​Parameters

​keyword (optional)

​cursor (optional)

​size (optional)

​Response Format

​Success Response (search_user_folders)

​Usage Examples

​Example 1: search_user_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

​User API key required

​Team API key required

​Insufficient scope

​Token Usage

​Scope Requirements

​Related Tools

Overview

Parameters

keyword (optional)

cursor (optional)

size (optional)

Response Format

Success Response (search_user_folders)

Usage Examples

Example 1: search_user_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

User API key required

Team API key required

Insufficient scope

Token Usage

Scope Requirements

Related Tools