Computer-Use Agents API

List Files

list_files

List files on a session's machine, newest first; by default its environment's own, such as a browser's downloads.

session_id is the id run_agent returns, or an env-manager session id.

When a listing is truncated, page on the last entry's modified_at (ISO-8601) and name, passed as modified_before and name_after. Send both: modification times are not unique, and a timestamp alone skips the rest of a tied group.

Input Schema

Name	Required	Description	Default
`path`	No
`name_after`	No
`session_id`	Yes
`max_entries`	No
`modified_before`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 29, 2026
- addedInput schema / properties / path / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- changedInput schema / properties / path / default
```
Previous value: -"~/Downloads"New value: +null
```
- removedInput schema / properties / path / type
```
Removed value: -"string"
```
Changed1 schema field changedOct 5, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
AddedAug 13, 2026

TDQS

A3.6/5.0

Behavior4/5

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

With no annotations, the description carries the behavioral burden and does well: it discloses ordering (newest first), default scope (environment's own files), truncation behavior, and the subtle tie-breaking requirement when paging on modified_at and name. It does not explicitly state that the operation is read-only/safe or describe error behavior, leaving some gaps.

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?

Front-loaded with purpose and ordered sensibly: what it lists, session_id provenance, then pagination. The pagination paragraph is dense but every sentence adds necessary operational detail, and there is no filler.

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?

The output schema exists, so return values need not be explained. But with five parameters at 0% schema description coverage and no annotations, the description should say more about max_entries, path semantics, and the read-only nature of the operation. It covers the trickiest pagination behavior well but is not fully complete.

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 0%, so the description must compensate. It explains session_id provenance and the pagination parameters (modified_before, name_after) with important ISO-8601 and tie-breaking detail, and implies the default for path. However, max_entries is never mentioned and path is only indirectly referenced, leaving two of five parameters underserved.

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 files on a session's machine'), plus ordering ('newest first') and default scope ('its environment's own, such as a browser's downloads'). The purpose is unmistakable and implicitly distinguishes listing from reading/writing siblings, but no sibling tool is named explicitly for contrast.

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?

Gives useful context for what the default listing covers and detailed instructions for paginating truncated results, but never states when to use this tool versus alternatives like read_file or when a path should be supplied. Usage is implied rather than explicitly guided.

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

All Computer-Use Agents API tools Inspect

Try in Browser

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.