Skip to main content
Glama

List folders

list_folders
Read-only

Lists mail, calendar, contact, or task folders with paths, IDs, names, and item/unread counts, so you can use the correct folder path or ID in later operations.

Instructions

List mailbox folders with their paths, IDs, well-known names and item/unread counts. Use the returned path or ID wherever a folder is expected.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_folders"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNoFolder type to list (default "mail")
refreshNoBypass the five-minute folder cache

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine context beyond that — the shape of each folder record and the fact that returned paths/IDs are the canonical references to pass downstream — but says nothing about ordering, hierarchy, or the cache behavior implied by the refresh parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both load-bearing: the first declares what is returned, the second tells the agent what to do with the result. Front-loaded resource statement and zero filler or restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, fully annotated, zero-required-parameter read tool with complete schema coverage and no output schema, the description covers purpose and return contents adequately. Minor omissions: whether results are hierarchical, ordering, and why the narrow "mailbox" framing conflicts with the broader kind enum.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both parameters documented (kind enum including "all", and refresh bypassing the five-minute cache), so the baseline of 3 applies. The description adds no meaning beyond the schema — it never mentions kind, the default of mail, or what refresh changes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List mailbox folders") plus the exact fields returned — paths, IDs, well-known names, item/unread counts — which no sibling tool offers. It does not name or contrast any alternative, and "mailbox folders" slightly under-describes the tool, since the kind parameter also lists calendar, contacts and tasks folders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage guidance is implied by the resource name plus one downstream hint: "Use the returned path or ID wherever a folder is expected." That is about consuming the output, not about when to pick this tool over alternatives (e.g. list_calendars, get_mailbox_info) or when to skip it, so the when-to-use dimension remains unaddressed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.