list_files

Use list_files before editing when you need the current model tree or a path prefix. Follow with read_file for content or commit_files for coordinated edits.

read-only · idempotent

Parameters

Name	Type	Required	Default	Description
model_name	Annotated[str, Field(description='Name of the Bridge Town model.')]	Yes	—
path	Annotated[str, Field(description="Optional subtree path to list or search within (e.g. 'model'). A single harmless trailing slash (e.g. 'model/') is stripped automatically. Omit to cover all files.")]	No	''
branch	`Annotated[str	None, Field(description=“Branch to operate on. Defaults to the model’s default branch when omitted or null.”)]`	No	None
max_results	Annotated[int, Field(description='Listing mode only. Maximum number of files to return. Defaults to 1000. Results are truncated when the total exceeds this.')]	No	100
pattern	Annotated[str, Field(description="Optional glob pattern to filter filenames (e.g. '*.py', 'model/**/*.py'). Applied after path filtering, in both listing and content-search (query) mode.")]	No	''
query	Annotated[str, Field(description='Optional text or regex to search file *contents* for. Setting this switches list_files from directory listing to grep-style content search — matches/files_scanned/files_with_matches/skipped_files/files_truncated are returned instead of files/count/total_count/truncated (formerly the standalone search_model_files tool). A literal, case-insensitive substring by default; set regex=True to treat it as a Python regular expression, and case_sensitive=True for case-sensitive matching either way.')]	No	''
context_lines	Annotated[int, Field(description=f'Query mode only. Lines of context to include before/after each match. Defaults to {_SEARCH_DEFAULT_CONTEXT_LINES}, max {_SEARCH_MAX_CONTEXT_LINES}.')]	No	2
max_matches	Annotated[int, Field(description=f'Query mode only. Maximum number of matches to return across all files. Defaults to {_SEARCH_DEFAULT_MAX_MATCHES}, max {_SEARCH_MAX_MATCHES_CAP}.')]	No	200
max_files	Annotated[int, Field(description=f'Query mode only. Maximum number of files to scan. Defaults to {_SEARCH_DEFAULT_MAX_FILES}, max {_SEARCH_MAX_FILES_CAP}.')]	No	200
regex	Annotated[bool, Field(description='Query mode only. Treat query as a Python regular expression. Defaults to False.')]	No	False
case_sensitive	Annotated[bool, Field(description='Query mode only. Case-sensitive matching. Defaults to False.')]	No	False
workspace_id	`Annotated[str	None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`	No	None

Returns

Returns a structured object. Top-level fields:

• model (string)
• path (string)
• branch (null)
• files (array<object>)
• count (integer)
• total_count (integer)
• truncated (boolean)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "list_files",
  "arguments": {
    "model_name": "forecasts",
    "path": "model",
    "pattern": "*.py",
    "max_results": 50
  }
}

Response

{
  "model": "forecasts",
  "path": "model",
  "branch": null,
  "files": [
    {
      "name": "revenue.py",
      "path": "model/revenue.py",
      "size": 482,
      "type": "file"
    },
    {
      "name": "headcount.py",
      "path": "model/headcount.py",
      "size": 612,
      "type": "file"
    }
  ],
  "count": 2,
  "total_count": 2,
  "truncated": false
}

Notes

• Module: Files
• Requires authentication via API token or Auth0 JWT.