Skip to main content
Glama

List Directory

list_directory

List files and subdirectories for a given path with sizes and optional hidden/build folder inclusion, enabling clear inspection and filtering of project contents.

Instructions

List files and directories inside a given directory with size and clean filtering.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>"
    },
    "name": "list_directory"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesRelative or absolute path to the directory.
include_hiddenNoIf True, includes hidden and build directories (.git, node_modules, etc.).

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.1.0
    • addedInput schema / properties / include_hidden
      Added value: +{
      +  "default": false,
      +  "description": "If True, includes hidden and build directories (.git, node_modules, etc.).",
      +  "type": "boolean"
      +}
  2. First observedv2.0.0

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full behavioral burden, but it discloses almost nothing: whether the listing is recursive or single-level, ordering, error behavior on a missing path, or whether symlinks/permissions are considered. 'With size' and 'clean filtering' gesture at return content and default exclusion of build directories, but the schema's include_hidden parameter already states the .git/node_modules behavior more clearly.

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?

It is a single front-loaded sentence with no wasted preamble. The trailing phrase 'with size and clean filtering' is slightly vague filler rather than a crisp constraint, which keeps it from a 5.

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

Completeness3/5

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

An output schema exists and the two parameters are fully documented, so the description need not explain return values. However, for a directory-listing tool the key ambiguity an agent faces — recursion depth and ordering — is left unaddressed, and with no annotations there is no safety or side-effect context either.

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%, so both path and include_hidden are already documented, and the description adds no format, relative-path resolution, or filtering syntax beyond that. Baseline 3 applies since the schema does the heavy lifting.

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?

The description gives a specific verb and resource: list files and directories inside a given directory, which is more precise than the name alone. It does not differentiate itself from nearby siblings such as glob_files or file_info, so an agent still has to infer which listing tool to pick.

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

Usage Guidelines2/5

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

There is no explicit when-to-use guidance and no exclusion of alternatives like glob_files (pattern-based search) or file_info (single-path metadata). The only hint is the phrase 'clean filtering', which does not tell the agent when this tool is the right choice.

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