List folder contents

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose that the operation lists direct children only and returns specific fields (name, type, path, file size), which gives insight into the output. However, it omits details like permission requirements, error behavior, or whether the operation is read-only (though listing is inherently non-destructive). For a simple read operation, this is borderline acceptable, but the lack of annotation coverage makes a 3 appropriate.

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

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

The description is a single, compact sentence that immediately states the core action and the parameters. It front-loads the primary capability and includes the salient return fields without extraneous detail. Every phrase earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema), the description provides sufficient context: it states the scope (direct children), the return fields (name, type, path, file size), and the input flexibility (path or friendly name). It lacks any mention of error conditions or non-recursive behavior explicitly stated, but the phrase 'directly inside' conveys non-recursion. For a basic listing tool, this is nearly complete; a 4 reflects minor missing details like error handling or permission needs.

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

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

Schema description coverage is 100% — the parameter 'path' is described as "Folder path, or a friendly name like \"documents\"" and the tool description repeats this exact idea. The description adds no new semantic meaning beyond what the schema already provides. Per the baseline rule for high schema coverage, a 3 is appropriate; the description does not compensate because it only echoes the schema.

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

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

The description uses a clear verb-resource pair ("List the files and subfolders directly inside a folder") and explicitly scopes it to direct children, which distinguishes it from siblings like list_open_folders (which lists open windows) and find_duplicate_files (which searches for duplicates). The mention of returning name, type, path, and file size further specifies what the tool does.

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

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

The description says it accepts both a path and a friendly folder name, which gives some context on inputs. However, it does not explicitly state when to use this tool versus alternatives or when not to use it. The sibling context (e.g., list_open_folders, find_duplicate_files) makes the distinction inferable, but the description itself lacks explicit routing guidance. A 4 is reasonable because the context is clear, though exclusions are not spelled out.

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