Bridge Town

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.

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).

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.

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).

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.

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.

Use commit_files for atomic multi-file changes, especially model plus run.py edits

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 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 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.

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.

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.

Create a new file in a Bridge Town project and commit it. The path is project-relative (e.g. 'README.md', 'model/revenue.py', 'data/seed.csv', 'assets/logo.png'). Specify branch to commit to a non-default branch (e.g. a scenario branch). Omitting branch, passing an empty string, or passing null all resolve to the project's default branch.

Use create_project to start a new model workspace

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.

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.

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.

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.

Delete a file from a Bridge Town project. The path is project-relative (e.g. 'README.md', 'model/revenue.py', 'data/seed.csv', 'assets/logo.png'). Specify branch to delete from a non-default branch (e.g. a scenario branch). Defaults to the project's default branch when branch is omitted. Pass expected_sha (the sha returned by read_file) to enable optimistic concurrency control: if another session modified the file since you last read it the tool raises a ToolError with the current SHA.

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.

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).

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.

Use describe_model for static model metadata without executing code

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.

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.

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).

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}.

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.

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.

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.

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.

Use get_run to poll or inspect one run by run_id

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.

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.

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.

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).

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

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).

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.

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.

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.

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.

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).

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.

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.

Use list_data_sources before query_data so table and column names are grounded in the live project catalog.

Use list_files before editing when you need the current project tree or a path prefix

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).

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.

Use list_projects first when the user refers to a project by memory or asks what they can access

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.

Use list_runs to find recent execution history before selecting a run_id

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.

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.

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.

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.

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.

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}.

Use patch_file for a small known text replacement in one file

Use query_data for read-only DuckDB analysis against project data sources

Use read_file to inspect an existing model, run.py, README, or data seed before making changes

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.

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).

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.

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).

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.

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.

Use run to execute a project via run.py or one model file

Use search_tools when the task is clear but the tool name is unknown

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).

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.

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.

Overwrite an existing file in a Bridge Town project and commit the change. The path is project-relative (e.g. 'README.md', 'model/revenue.py', 'data/seed.csv', 'assets/logo.png'). This tool is strict update-only: if the file does not exist it returns a not-found error instructing you to use create_file instead. Specify branch to commit to a non-default branch (e.g.

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.

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"}.