describe_model

Use describe_model for static model metadata without executing code. Follow with run_model only after the contract and required inputs are understood.

Parameters

Name	Type	Required	Default	Description
model_name	Annotated[str, Field(description='Name of the Bridge Town model.')]	Yes	—
path	Annotated[str, Field(description="Model-relative path of a Python model file to statically describe (e.g. 'model/revenue.py'). Omit to get a bounded model-level overview instead of a single-file contract.")]	No	''
include	`Annotated[list[Literal[‘branches’, ‘runs’, ‘data_sources’, ‘dashboards’]]	None, Field(description=“Overview mode only (path omitted). Which bounded sections to add beyond files: ‘branches’ (recent branches), ‘runs’ (recent run summaries), ‘data_sources’ (attached data sources), or ‘dashboards’ (saved dashboard provenance and run freshness). Defaults to [‘branches’] — the model-inventory view. Pass [‘runs’, ‘data_sources’] for the model-review-context view used before proposing a logic change.”)]`	No	None
branch	`Annotated[str	None, Field(description=“Branch to read from. Single-file mode: read path from this branch. Overview mode: scope files/runs to this branch. Defaults to the model’s default branch when omitted or null.”)]`	No	None
max_files	Annotated[int, Field(description='Overview mode only. Maximum file entries; defaults to and is capped at 50.')]	No	50
max_branches	Annotated[int, Field(description='Overview mode only. Maximum branch entries; capped at 50.')]	No	20
max_runs	Annotated[int, Field(description='Overview mode only. Maximum run summaries; capped at 20.')]	No	5
max_data_sources	Annotated[int, Field(description='Overview mode only. Maximum data-source entries; capped at 20.')]	No	20
max_dashboards	Annotated[int, Field(description='Overview mode only. Maximum dashboard entries; capped at 20.')]	No	10
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>)
• file_count (integer)
• total_count (integer)
• returned_count (integer)
• omitted_count (integer)
• truncation_reason (string)
• continuation_guidance (string)
• truncated (boolean)
• follow_up (object)
• workspace_id (string)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "describe_model",
  "arguments": {
    "model_name": "forecasts",
    "include": [],
    "max_files": 2
  }
}

Response

{
  "model": "forecasts",
  "path": "",
  "branch": null,
  "files": [
    {
      "name": "headcount.py",
      "path": "model/headcount.py",
      "size": 612,
      "type": "file"
    },
    {
      "name": "revenue.py",
      "path": "model/revenue.py",
      "size": 482,
      "type": "file"
    }
  ],
  "file_count": 2,
  "total_count": 3,
  "returned_count": 2,
  "omitted_count": 1,
  "truncation_reason": "max_files",
  "continuation_guidance": "Call list_files with model_name='forecasts', branch=None, max_results=3, workspace_id='dddddddd-dddd-dddd-dddd-dddddddddddd' to retrieve all 3 inventory entries.",
  "truncated": true,
  "follow_up": {
    "read_file": "Read one file path from files[].path.",
    "describe_model": "Pass path to inspect one Python file's static contract."
  },
  "workspace_id": "dddddddd-dddd-dddd-dddd-dddddddddddd"
}

Notes

• Module: Files
• Requires an authenticated Bridge Town session (OAuth) or an API token.