list_files
Use list_files before editing when you need the current project tree or a path prefix
describe_model
Use describe_model for static model metadata without executing code
list_projects
Use list_projects first when the user refers to a project by memory or asks what they can access
delete_project
Delete a Bridge Town project. Requires Owner role on the project. This permanently removes the project and all its git history, files, and collaborator grants. The action cannot be undone. Safety: defaults to dry_run=True to confirm you are targeting the right project. The dry-run response lists what will be deleted without mutating anything and returns a confirmation_token.
create_project
Use create_project to start a new model workspace
list_project_collaborators
List all active and pending collaborators for a project. Requires at least Viewer role on the project. Returns: project (str); collaborators (list[{grant_id, user_id, email, display_name, role, pending}]); count (int). Pending entries have user_id=null and pending=true — the invitee has not yet joined the workspace.
invite_project_collaborator
Invite a user to a project by email. Requires Owner role on the project. If the email belongs to an active workspace member, access is granted immediately and they receive a project-access email. Otherwise a pending project grant and workspace invitation are created together — the invitee receives a workspace invite email and both grants are resolved when they sign up.
change_collaborator_role
Change the project role for an active collaborator. Requires Owner role on the project. target_user_id: UUID of the collaborator to update. role: one of 'viewer', 'editor', 'owner'. Cannot demote the only project owner. Returns: grant_id, project, user_id, new_role.
remove_project_collaborator
Remove an active collaborator from a project using their target_user_id. Requires Owner role on the project. To cancel a pending invite instead, use cancel_project_invite with the invite_id (grant_id) returned by invite_project_collaborator. Cannot remove the only project owner. Returns: project, user_id, removed (bool).
cancel_project_invite
Cancel a pending project invite before the invitee signs up. Requires Owner role on the project. invite_id: the grant_id returned by invite_project_collaborator. Returns: project, invite_id, cancelled (bool).
get_skill
Look up a Bridge Town skill by exact name or natural-language query. Use when you know a skill name or need to find one from a description. Set include_template=true to get the full prompt template.
create_branch
Create a new git branch in a project. Use this to start a scenario branch for testing alternative assumptions. Scenario workflow: (1) create_branch to start the scenario, (2) patch_file for small edits or update_file for larger changeson the scenario branch, (3) compare_branches to run both branches and diff the outputs, (4) merge_branch (Owner only) to adopt the winning scenario into main, or create_pull_request for team review before merging.
list_branches
List branches in a project. Requires at least Viewer role. Use max_results to bound the response size (default 100, max 1000). When the result is truncated, the response includes truncated=true and total_count so you know how many branches exist in total.
merge_branch
Merge a head branch into a base branch (direct merge, no review required). If the merge would cause conflicts, returns a human-readable diff showing the conflicting changes so you can resolve them manually. Requires Owner role — only Owners can directly merge branches into main, protecting the base model from unreviewed assumption changes.
delete_branch
Delete a branch from a project. The default branch (main) cannot be deleted. Typically used to clean up scenario branches after merge_branch or merge_pull_request. Requires Owner role. DESTRUCTIVE — defaults to dry_run=True and returns a confirmation_token. To execute: call again with dry_run=False and echo the token.
create_pull_request
Open a merge request (pull request) from head_branch into base_branch. Use this to start a team review workflow before merging a scenario branch. Requires at least Editor role. Returns: id (int) — PR number; title (str) — PR title; state (str) — always 'open' on creation; head_branch (str) — source branch; base_branch (str) — target branch; author (str) — creator login; created_at (str) — ISO timestamp; merged (bool) — always false on creation.
list_pull_requests
List pull requests (merge requests) in a project. Requires at least Viewer role. state filter: 'open' (default), 'closed', or 'all'. Returns: project (str) — project name; pull_requests (list) — PR summaries with id, title, state, head_branch, base_branch, author, created_at, merged; count (int) — number of PRs returned; state_filter (str) — the state filter applied.
get_pull_request
Get full detail for a pull request, including the unified diff. Requires at least Viewer role. Returns: id (int) — PR number; title (str); body (str) — PR description; state (str) — open or closed; head_branch / base_branch (str) — source and target branches; author (str) — creator login; created_at / updated_at (str) — ISO timestamps; merged (bool); merged_at (str | null) — merge timestamp when merged; diff (str) — unified diff of all changes in the PR.
review_pull_request
Submit a review decision on a pull request. Requires at least Editor role. event options: 'comment' (neutral feedback), 'approve' (signal ready to merge), 'request_changes' (block merge until addressed). Returns: project (str); pull_request_id (int); event (str); message (str).
merge_pull_request
Merge an approved pull request into its base branch. Requires Owner role. style options: 'merge' (merge commit, default), 'squash' (squash into one commit), 'rebase' (rebase onto base branch). Safety: pass expected_head_sha (the PR head commit SHA from get_pull_request) to guard against new commits pushed to the PR branch since you last checked. Returns: project (str); pull_request_id (int); merged (bool); message (str); audit_id (str) — correlation ID present in the audit log for this merge.
query_data
Use query_data for read-only DuckDB analysis against project data sources
list_data_sources
Use list_data_sources before query_data so table and column names are grounded in the live project catalog.
ingest_data_source
Make a data source queryable in Bridge Town. Handles file uploads and connected Google Sheet snapshots through one discriminated schema. Uses a discriminated spec.kind schema. kind='file_upload': encode a CSV or Excel file as base64 in spec.file_content. kind='google_sheet_snapshot': reference a connected sheet by spec.source_name or spec.data_source_id — the sheet must be connected via the Bridge Town web app.
get_spreadsheet_metadata
Return metadata for a connected Google Sheet: the spreadsheet title, and for each tab the sheet ID, title, index, type, row count, and column count. Use this before write-back tools (write_gsheet) to discover available tabs and their dimensions. Target the sheet by source_name (from list_data_sources) OR spreadsheet_id — source_name is preferred for linked sheets.
batch_read_gsheet_ranges
Read multiple ranges from a connected Google Sheet in a single API call. Returns the values for each requested A1-notation range. Target the sheet by source_name (from list_data_sources) OR spreadsheet_id. Requires at least Viewer role on the project. Returns: spreadsheet_id, ranges (list of {range, values}), sheet_url. On error: error, message, hint.
write_gsheet
Consolidated Google Sheets write tool. Provide `spec.mode` to choose one operation: `replace`, `append`, `clear`, `batch`, or `new_spreadsheet`. Examples: 1) Replace model output in a target range: {"mode":"replace","run_id":"...","output_name":"forecast.json","cell_range":"Forecast!A1"}. 2) Append model output to a tab: {"mode":"append","run_id":"...","output_name":"forecast.json","sheet_name":"History"}.
modify_gsheet_structure
Consolidated Google Sheets structure tool. Use `spec.action` as a discriminator: `ensure_tab`, `insert_rows`, or `delete_rows`. Examples: 1) Ensure a tab exists: {"action":"ensure_tab","tab_title":"Forecast"}. 2) Insert rows: {"action":"insert_rows","sheet_id":0,"start_row":1,"num_rows":3}. 3) Delete rows: {"action":"delete_rows","sheet_id":0,"start_row":20,"num_rows":5}.
format_gsheet
Unified Google Sheets formatting tool using discriminated spec.kind. Supported kinds: range_format, borders, freeze_panes, protect_range, validation, conditional_format, preset, list_presets. Examples: 1) Apply direct range styling: {"kind":"range_format","sheet_id":0,"start_row":0,"end_row":1,"start_col":0,"end_col":5,"bold":true}.
list_snapshots
List available data snapshots for a project with their creation dates and sizes. Snapshots are grouped by upload batch. A snapshot is marked 'referenced' if it is used by a model run and cannot be deleted. Use 'delete_snapshot' to remove unreferenced snapshots. Returns: project_name (str) — project name; snapshots (list[{timestamp, prefix, file_count, total_size_bytes, referenced}]) — one entry per batch; total_count (int) — number of snapshot batches.
delete_snapshot
Delete an unreferenced snapshot batch from S3. The snapshot prefix must match exactly the 'prefix' field returned by 'list_snapshots'. Snapshots referenced by a model run cannot be deleted and will return an error. This operation is irreversible. Returns: project_name (str) — project name; snapshot_prefix (str) — prefix of the deleted batch; deleted_count (int) — number of S3 objects removed.
list_chart_types
List all available dashboard chart types and their required data schemas. Call this before create_dashboard to discover which chart types are supported and what keys your model output must contain for each type. No project access required — returns static metadata only. Note: MCP transport authentication is still required (POST /mcp requires a valid JWT).
create_dashboard
Create or update a saved dashboard for a Bridge Town project. Generates chart HTML from a completed model run output, stores it in S3, and persists a Dashboard record. Requires Editor or Owner access to the project. output_key selects a key from the run's outputs dict — the same dict your model writes to /outputs/. When a model writes a JSON file such as `/outputs/chart_data.json`, the run's outputs dict stores it under the full filename including the extension (e.g.
share_dashboard
Mark a saved dashboard as shared with the project team and return an authenticated app URL. The URL can only be opened by users who already have Bridge Town access to the project — no anonymous or public access is granted. Requires at least Editor access to the project. expires_hours: enforced sharing duration in hours (1–168, default 24).
list_dashboards
List saved dashboards for a Bridge Town project. Requires at least Viewer access to the project. Returns: project (str) — project name; dashboards (list[{name, description, is_shared, share_expires_at, has_html, created_at, updated_at}]) — one entry per dashboard; is_shared reflects only currently-active shares (false when expired); share_expires_at is the ISO-8601 UTC expiry timestamp, or null for no-expiry shares; count (int) — number of dashboards.
run
Use run to execute a project via run.py or one model file
get_run
Use get_run to poll or inspect one run by run_id
get_run_output
Retrieve a single named output from a completed model run. Use this instead of get_run when you only need one output and want to avoid the 1 MiB truncation cliff for large multi-tab runs. Resolves run_id using full UUID or UUID prefix. Requires a successful run status.
list_runs
Use list_runs to find recent execution history before selecting a run_id
cancel_run
Cancel a pending or running model execution. Returns: run_id (str) — cancelled run UUID; status (str) — always 'cancelled'; project_name (str) — project name; message (str) — confirmation message.
list_versions
List the version history (git commits) for a Bridge Town project. When path is provided (e.g. ``model/revenue.py``, ``README.md``, ``data/seed.csv``), only commits that touched that file are shown; omit path to list project-wide history. Each version includes the commit SHA, human-readable commit message (derived from the natural-language prompt used to create or update the file), author name, and date.
diff
Show a unified diff between two refs (commit SHAs or branch names) of a Bridge Town project. Refs are detected automatically: a ref consisting of 7–40 hexadecimal characters is treated as a commit SHA; anything else is treated as a branch name. Use list_versions to find commit SHAs. The diff shows exactly what changed between ref_a and ref_b across all files, or only the specified file when path (e.g.
rollback_version
Restore a project file to the bytes it had at a previous version (commit SHA). Pass path as a project-relative file path (e.g. ``model/revenue.py``, ``README.md``, ``data/seed.csv``, ``assets/logo.png``). This creates a new commit — it does NOT rewrite history. Use list_versions to find the commit SHA you want to restore. Optionally specify a branch to restore on a scenario branch instead of the default branch.
request_model_share
Request to share a Bridge Town model with another tenant. Creates a pending share request that the target tenant must explicitly accept. No model code is written to the target repo until acceptance. Requires at least Viewer access to the source project. Requires Pro plan. Returns: request_id, status='pending', source_project, source_model, target_tenant, suggested_target_project, suggested_target_model, created_at.
list_model_share_requests
List model share requests for the current tenant. direction='incoming' shows requests targeting this tenant; direction='outgoing' shows requests this tenant initiated; direction='all' (default) shows both. Filter by status: 'pending', 'accepted', 'rejected', 'revoked', or 'all' (default). Returns: requests (list with full status, commit SHAs, and timestamps).
accept_model_share_request
Accept a pending model share request. Caller must have Owner or Editor access to the target project in the current tenant. Writes the source model to the target repo with a provenance header. If the target path already exists, expected_sha (the current Gitea blob SHA) is required to confirm an explicit overwrite; omitting it returns a conflict error with the current SHA and a recovery hint.
reject_model_share_request
Reject a pending model share request. Caller must have Owner or Editor access to the suggested target project in the target tenant. If the target project does not yet exist, workspace Owner role is also accepted. Returns: request_id, status='rejected', updated_at.
sync_shared_model
Re-sync an accepted model share with the latest source content. Caller must have Owner or Editor access to the target project in the current tenant. If the target file already exists, expected_sha (the current Gitea blob SHA) is required to confirm the overwrite; omitting it returns a conflict error with the current SHA and a recovery hint. Returns: request_id, target_project, target_model, target_path, source_commit_sha, target_commit_sha, synced_at.
revoke_model_share
Revoke an accepted model share. Source tenant members with Owner or Editor access to the source project may revoke. Target tenant members with Owner or Editor access to the accepted target project may revoke. Records the revocation in the audit trail; does NOT delete the file from the target repo — the target tenant retains their copy. Returns: request_id, status='revoked', updated_at.
create_project_from_template
Create a new project using an internal workspace template as its starting point. Any workspace member may call this tool. The new project starts with a full copy of the template's code and version history. Data-source credentials and prior run outputs are NOT copied. Provenance is recorded so the new project's origin is traceable.
compare_branches
Run a project on two branches concurrently and compare the resulting outputs side-by-side. Returns a structured project-output diff with absolute and percentage deltas for every changed metric. Changes of 10% or more are flagged as significant. Both branches run against the same data snapshot for an apples-to-apples comparison.
compare_runs
Compare two persisted model-run outputs side-by-side. Resolves run IDs using full UUID or UUID prefix. Both runs must be successful and belong to the same accessible project. Uses base_run_id as the anchor and comparison_run_id as the changed side in returned labels and deltas. Reuses the same diffing engine as compare_branches so result semantics stay aligned.
create_commentary
Attach narrative analysis to a model run, or to one named output of the run. Use this after compare_runs / get_run_output to save the agent's interpretation alongside the data it explains. If output_name is omitted, the commentary is run-level. If output_name is provided and the run has output data available, the name is validated against the same resolver as get_run_output.
list_commentary
Discover run commentary across runs and projects accessible to the caller. All filters are AND-composed. When project_name and run_id are both omitted, the result is constrained to the caller's accessible projects so commentary from foreign projects is never leaked. Pass include_archived=true to surface soft-deleted rows for audit/recovery flows. Returns: commentary (list) — each entry mirrors the create response; total_returned (int) — the count of rows returned.
get_commentary
Fetch one commentary row by id, optionally with its full version history. Use this when the caller already has a commentary_id (e.g. from list_commentary) and wants the current text or the complete edit trail. Pass include_versions=true to receive the append-only history ordered oldest-first; the trail is exactly the rows persisted by prior create/update_commentary calls.
update_commentary
Edit commentary text under optimistic concurrency. Pass the version you observed last (typically the value returned by create_commentary or get_commentary) as expected_version; if it no longer matches the stored row, the tool returns a commentary-stale-version error carrying expected_version and actual_version so the caller can re-fetch and merge.
archive_commentary
Soft-delete a commentary row by stamping archived_at / archived_by. Idempotent: archiving an already-archived row is a no-op that returns the existing row unchanged. Archived rows are hidden from list_commentary by default; pass include_archived=true to that tool to surface them. Archiving does NOT bump the version or append a version row (the trail tracks text edits, not lifecycle).
list_scheduled_runs
List all scheduled recurring model runs for a project. Use create_scheduled_run to add a new schedule, update_scheduled_run to change an existing one, or delete_scheduled_run to remove one. Cadence: 5-field UTC cron expression. Minimum interval: 15 minutes. Returns: schedules (list) — each schedule's ID, cadence, enabled flag, next/last run times, and consecutive failure count; count (int) — number returned; message (str) — summary.
create_scheduled_run
Create a new scheduled recurring model run for a project. cadence is required: a 5-field UTC cron expression (minute hour day_of_month month day_of_week). Examples: '0 8 * * 1' (every Monday 08:00 UTC), '0 0 1 * *' (monthly). Minimum interval: 15 minutes. All times are UTC. Runs appear in list_runs, get_run, and compare_runs once triggered.
update_scheduled_run
Update an existing scheduled model run. schedule_id is required (from list_scheduled_runs). Pass only the fields you want to change: cadence (new cron expression), enabled (pause or resume), branch (switch target branch), model_name (switch target model). Cadence validation: 5-field UTC cron, minimum 15-minute interval. Returns: schedule (dict) — updated schedule summary; message (str) — update summary.
delete_scheduled_run
Delete a scheduled model run. DESTRUCTIVE — defaults to dry_run=True: previews what would be deleted and returns a confirmation_token valid for 5 minutes. To execute: call again with dry_run=False and echo the confirmation_token. schedule_id is required (from list_scheduled_runs).
get_usage
Return current-period usage counters for the authenticated tenant: project count vs quota, API token count vs quota, and model-run minutes consumed in the current UTC calendar month. Use this to answer 'am I close to a limit?' without a separate REST round-trip. Returns: projects_used (int), projects_quota (int), tokens_used (int), tokens_quota (int), run_minutes_used_this_month (float), run_minutes_quota (int|null), reset_date_iso (str ISO-8601).
get_subscription
Return subscription status for the authenticated tenant: plan name, Stripe subscription status, current billing period end, and whether the subscription is set to cancel at period end. Use this when the user asks about their plan, billing, or renewal state. Returns: plan (str), stripe_subscription_status (str|null), current_period_end_iso (str ISO-8601|null), cancel_at_period_end (bool).
import_project
Import a Bridge Town project from a ``.btx`` archive file. Pass the staged_import_id UUID returned by POST /api/projects/imports/stage after uploading the archive. Returns: job_id (str) — import job UUID for polling via get_import; status (str) — queued/pending state; target_workspace_id (str) — destination workspace; target_repo_name (str|null) — destination project; message (str) — next action; duplicate_of (str|null) — idempotent prior job.
get_import
Poll an import job by ``job_id``. Returns: job_id (str) — import job UUID; status (str) — current job state; target_workspace_id (str|null) — destination workspace; target_repo_name (str|null) — destination project; message (str) — status summary; error (str|null) — failure detail when present.
export_project
Queue a portable ``.btx`` archive export for a Bridge Town project. Poll ``get_export(job_id)`` for completion and the pre-signed download URL. Returns: job_id (str) — export job UUID; status (str) — queued/pending status; project_id (str) — project slug; message (str) — next action; warning (str|null) — optional clamping or staging warning.
get_export
Poll a ``.btx`` export job by ``job_id``. When the job has completed successfully the response includes a pre-signed ``download_url`` and ``download_url_expires_at`` (UTC, ISO-8601). Issuing the URL emits a synchronous SOC2 audit event; if the audit subsystem is unavailable the tool refuses to surface the URL.
export_run_output
Export completed model run outputs to a downloadable XLSX workbook or PDF table pack. Returns a time-limited pre-signed S3 download URL. Only successful runs can be exported. Supports list-of-dict (tabular) outputs; non-tabular outputs are skipped when output_name is omitted, or produce an error when named explicitly. Returns: run_id, project_name, format, output_names (list), skipped_output_names (list), file_size_bytes, download_url, download_url_expires_at (ISO-8601 UTC).
search_tools
Use search_tools when the task is clear but the tool name is unknown
get_tool
Use get_tool after search_tools or when a prompt names a tool and you need the exact schema, annotations, usage guidance, and related tools