Skip to main content
Glama
PhononX

Carbon Voice

by PhononX
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

get_folder

Read-only

Fetch a folder's metadata and optionally its immediate subfolders, returning structure and nested counts. Use to inspect folder hierarchy.

Instructions

Get one folder's metadata and, optionally, its immediate subfolders. USE WHEN: Inspecting a folder. Set include_first_level_tree: true to get subfolders. Both date AND direction are silently ignored unless you do — upstream only documented that caveat on date. USE INSTEAD: get_folder_with_messages when you want the messages inside the folder — this returns structure and counts only. FIRST: id comes from get_root_folders (field results[].id) — call it first if you don't have one. EXAMPLE: {"id":"folder-abc","include_first_level_tree":true} RETURNS: {id, name, type, workspace_id, parent_folder_id?, path?, subfolder_ids?, message_ids?, total_nested_folders_count, total_nested_messages_count, subfolders?, ...}.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYes
dateNoReturn only subfolders updated relative to this date and `direction`. Only takes effect when `include_first_level_tree` is true — otherwise it is silently ignored.
directionNoDirection of the results (newer or older). Only takes effect when `include_first_level_tree` is true — otherwise it is silently ignored.newer
response_fieldsNoDot-path allowlist to shrink the response, e.g. ["results.id","total"]. Omit for the full payload.
include_first_level_treeNoDefines if the first level of the folder tree should be returned

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv2.10.0
    • changedInput schema / properties / date / description
      Previous value: -"Return only Subfolders updated based on the date and direction (must inform include_first_level_tree = true)"New value: +"Return only subfolders updated relative to this date and `direction`. Only takes effect when `include_first_level_tree` is true — otherwise it is silently ignored."
    • changedInput schema / properties / direction / description
      Previous value: -"Direction of the results (newer or older)"New value: +"Direction of the results (newer or older). Only takes effect when `include_first_level_tree` is true — otherwise it is silently ignored."
    • addedInput schema / properties / response_fields
      Added value: +{
+  "description": "Dot-path allowlist to shrink the response, e.g. [\"results.id\",\"total\"]. Omit for the full payload.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

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

The description discloses a non-obvious and potentially dangerous behavioral quirk: both date and direction are silently ignored unless include_first_level_tree is true. It also explains that this tool returns only structure and counts, not message contents, and includes a return shape with optional fields. The annotations already declare readOnly and non-destructive, so no contradiction exists and the extra caveat meaningfully adds transparency.

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

Conciseness4/5

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

The description is well-structured with clear labels and front-loaded purpose, then chunked into usage, alternative, prerequisite, example, and return sections. It is somewhat dense and includes a slightly cryptic phrase ('unless you do' and 'upstream only documented that caveat on date'), but overall every major section earns its place and improves usability.

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

Completeness5/5

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

There is no output schema, so the description compensates by providing a return shape and clarifying optional fields. It also covers the prerequisite call, the mutation-free read-only nature, the subfolder behavior, and the sibling distinction. For a 5-param tool with one required param, no output schema, and only read-only annotations, this is a complete and well-rounded definition.

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

Parameters4/5

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

Schema description coverage is 80%, so the baseline is already fairly high. The description adds important meaning for the undocumented id parameter by identifying its source and exact extraction path (get_root_folders results[].id), and it includes a concrete example. It mostly restates the schema for date, direction, and response_fields, but the id guidance plus example lifts it above baseline.

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

Purpose5/5

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

The description states a specific action and resource: retrieving one folder's metadata, with an optional subfolder tree. It explicitly names get_folder_with_messages as the alternative and clarifies this tool returns structure and counts only, so the agent can distinguish it from a related sibling.

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

Usage Guidelines5/5

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

It gives explicit 'USE WHEN' context for inspecting a folder, 'USE INSTEAD' guidance for get_folder_with_messages, and a 'FIRST' instruction to call get_root_folders for the id. This gives clear routing between alternatives and prerequisites, which is exactly what an agent needs to decide when to call it.

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

Deploy Server

Other Tools