MCP tools reference

Contractor Foreman MCP tools

15 tools for Contractor Foreman on the Cotlet MCP server. Your agent picks them from tools/list.

MCP server
https://cotlet.dev/mcp/v1
Connects with
Your own Contractor Foreman account (the role needs access to the modules you use)
Integration page
Contractor Foreman
Contractor Foreman Endpoints
Endpoint Access Description
contractor-foreman_list_projects read Projects with customer, address, stage, contract amount and percent complete.
contractor-foreman_get_project read One project: customer, address, stage, original and revised contract amount, dates.
contractor-foreman_get_job_costing read Estimated and actual cost per cost code for one project, with the difference.
contractor-foreman_list_estimates read Estimates with status, total, and whether the client opened or signed them.
contractor-foreman_list_change_orders read Change orders and change order requests on a project, with status and amount.
contractor-foreman_list_daily_logs read Daily logs on a project: date, people on site, weather, materials and notes.
contractor-foreman_list_schedule_tasks read Gantt schedule tasks with start and end dates, dependencies and percent complete.
contractor-foreman_list_invoices read Invoices with project, customer, total, amount paid, balance due and retainage held.
contractor-foreman_create_daily_log write New daily log on a project. Weather is recorded by Contractor Foreman for the date.
contractor-foreman_create_estimate write Draft estimate with line items and markup. Nothing goes to the client until you send it.
contractor-foreman_send_estimate write Email an estimate to the client for online approval and e-signature.
contractor-foreman_create_change_order write Draft change order on a project, itemized or lump sum. Not sent until you send it.
contractor-foreman_send_change_order write Email a change order to the client for online approval and e-signature.
contractor-foreman_update_schedule_task write Change dates or percent complete of a task on the project schedule.
contractor-foreman_add_punchlist_item write New punchlist item on a project, assigned to an employee or subcontractor.

List projects

read

MCP tool contractor-foreman_list_projects

Returns projects newest first. Completed projects are left out unless you ask for them. Search matches the project name, number or customer. Pages hold up to 100 projects; pass next_cursor back as cursor for the next page.

Parameters

Parameters: list_projects
NameTypeDescription
search string Match on project name, number or customer.
include_completed boolean Include completed projects. Default: false.
limit integer 1 to 100. Default: 25.
cursor string Next page cursor from the previous call.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_list_projects",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "projects": [
      {
        "project_id": "84213",
        "name": "Maple St Remodel",
        "number": "P-0142",
        "customer": "Dana Whitfield",
        "address": "218 Maple St, Asheville, NC",
        "stage": "In progress",
        "contract_amount": 86500,
        "percent_complete": 42
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

Get project

read

MCP tool contractor-foreman_get_project

Returns one project. The revised contract amount is the original amount plus approved change orders, as the project shows it. Use the project_id from list_projects.

Parameters

Parameters: get_project
NameTypeDescription
project_id required string Project ID from list_projects.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_get_project",
    "arguments": {
      "project_id": "project_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "project_id": "84213",
    "name": "Maple St Remodel",
    "customer": "Dana Whitfield",
    "address": "218 Maple St, Asheville, NC",
    "stage": "In progress",
    "original_contract_amount": 86500,
    "revised_contract_amount": 86500,
    "start_date": "2026-08-17",
    "end_date": "2026-12-11"
  },
  "isError": false
}

Get job costing

read

MCP tool contractor-foreman_get_job_costing

Returns the figures of the project's job costing: estimated cost, actual cost and the difference for each cost code, plus totals. Labor from time cards counts toward actual cost. Read only.

Parameters

Parameters: get_job_costing
NameTypeDescription
project_id required string Project ID from list_projects.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_get_job_costing",
    "arguments": {
      "project_id": "84213"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "project_id": "84213",
    "cost_codes": [
      {
        "code": "Labor",
        "estimated": 18000,
        "actual": 19250,
        "difference": -1250
      },
      {
        "code": "Materials",
        "estimated": 22000,
        "actual": 20100,
        "difference": 1900
      },
      {
        "code": "Subcontractors",
        "estimated": 9000,
        "actual": 9000,
        "difference": 0
      }
    ],
    "totals": {
      "estimated": 49000,
      "actual": 48350,
      "difference": 650
    },
    "currency": "USD"
  },
  "isError": false
}

List estimates

read

MCP tool contractor-foreman_list_estimates

Returns estimates newest first, optionally for one project. Status is the label Contractor Foreman shows, for example draft or approved. Pages hold up to 100 estimates.

Parameters

Parameters: list_estimates
NameTypeDescription
project_id string Only estimates for this project.
status string Filter by status as shown in Contractor Foreman, e.g. draft or approved.
limit integer 1 to 100. Default: 25.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_list_estimates",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "estimates": [
      {
        "estimate_id": "E-2291",
        "project_id": "84213",
        "title": "Bathroom remodel",
        "status": "draft",
        "total": 1589,
        "opened_by_client": false,
        "signed": false
      }
    ]
  },
  "isError": false
}

List change orders

read

MCP tool contractor-foreman_list_change_orders

Returns the change orders of one project with status and amount. Change order requests that are not yet in a change order are included unless you turn them off.

Parameters

Parameters: list_change_orders
NameTypeDescription
project_id required string Project ID from list_projects.
include_requests boolean Include change order requests not yet in a change order. Default: true.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_list_change_orders",
    "arguments": {
      "project_id": "project_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "change_orders": [
      {
        "change_order_id": "CO-17",
        "title": "Second kitchen window",
        "status": "draft",
        "amount": 1368
      }
    ]
  },
  "isError": false
}

List daily logs

read

MCP tool contractor-foreman_list_daily_logs

Returns the daily logs of one project, newest first, optionally between two dates. Each log carries the notes, the people on site, deliveries and the weather Contractor Foreman recorded.

Parameters

Parameters: list_daily_logs
NameTypeDescription
project_id required string Project ID from list_projects.
from date First log date.
to date Last log date.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_list_daily_logs",
    "arguments": {
      "project_id": "project_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "daily_logs": [
      {
        "daily_log_id": "557190",
        "date": "2026-10-09",
        "notes": "Framing second floor east wall.",
        "people": {
          "Framing crew": 4
        },
        "weather": {
          "condition": "Rain",
          "high_f": 61,
          "low_f": 48
        }
      }
    ]
  },
  "isError": false
}

List schedule tasks

read

MCP tool contractor-foreman_list_schedule_tasks

Returns the tasks of the project schedule in the order of the Gantt chart. Each task has start and end dates, the tasks it depends on and percent complete. Use the task_id with update_schedule_task.

Parameters

Parameters: list_schedule_tasks
NameTypeDescription
project_id required string Project ID from list_projects.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_list_schedule_tasks",
    "arguments": {
      "project_id": "project_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "tasks": [
      {
        "task_id": "T-5530",
        "name": "Rough-in inspection",
        "start_date": "2026-10-14",
        "end_date": "2026-10-14",
        "depends_on": [
          "T-5521"
        ],
        "percent_complete": 0
      }
    ]
  },
  "isError": false
}

List invoices

read

MCP tool contractor-foreman_list_invoices

Returns invoices newest first. Balance due is the total minus the amount paid. Retainage held is listed apart from it. Filter to invoices with a balance or due before a date. Pages hold up to 100 invoices.

Parameters

Parameters: list_invoices
NameTypeDescription
project_id string Only invoices for this project.
unpaid_only boolean Only invoices with a balance due. Default: false.
due_before date Only invoices due before this date.
limit integer 1 to 100. Default: 25.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_list_invoices",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "invoices": [
      {
        "invoice_id": "INV-1048",
        "project_id": "84213",
        "customer": "Dana Whitfield",
        "total": 12000,
        "paid": 7000,
        "balance_due": 5000,
        "retainage_held": 600,
        "due_date": "2026-09-05"
      }
    ]
  },
  "isError": false
}

Create daily log

write

MCP tool contractor-foreman_create_daily_log

Adds a daily log to the project for the date you give. Contractor Foreman records the weather itself; weather_notes sits next to it. The log reaches no client or crew and can be edited in the app, so this tool runs without asking.

Parameters

Parameters: create_daily_log
NameTypeDescription
project_id required string Project ID from list_projects.
date required date Log date.
notes required string Work done and site notes.
people object Crews, subcontractors and visitors on site, with headcount or names.
materials_delivered string[] Materials delivered to the site.
weather_notes string Your own notes next to the recorded weather.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_create_daily_log",
    "arguments": {
      "project_id": "84213",
      "date": "2026-10-09",
      "notes": "Framing second floor east wall. Window rough openings checked.",
      "people": {
        "Framing crew": 4,
        "Electrical sub": 1
      },
      "materials_delivered": [
        "48 sheets 1/2\" drywall",
        "20 2x6x12 studs"
      ],
      "weather_notes": "Rain after 2 pm, crew stopped at 2:30."
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "daily_log_id": "557190",
    "project_id": "84213",
    "date": "2026-10-09",
    "weather": {
      "condition": "Rain",
      "high_f": 61,
      "low_f": 48
    }
  },
  "isError": false
}

Create estimate

write

MCP tool contractor-foreman_create_estimate

Saves a draft estimate on the project. Each line total is quantity times unit cost plus its markup, and the estimate total is the sum of the lines. The client sees nothing until send_estimate, so this tool runs without asking.

Parameters

Parameters: create_estimate
NameTypeDescription
project_id required string Project ID from list_projects.
title required string Estimate title.
items required object Line items: name, item type (e.g. material or labor), quantity, unit cost, markup percent.
notes string Scope notes shown on the estimate.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_create_estimate",
    "arguments": {
      "project_id": "84557",
      "title": "Johnson bathroom remodel",
      "items": [
        {
          "name": "Demolition labor",
          "type": "labor",
          "quantity": 16,
          "unit_cost": 55,
          "markup_percent": 0
        },
        {
          "name": "Porcelain floor tile",
          "type": "material",
          "quantity": 60,
          "unit_cost": 8.5,
          "markup_percent": 20
        }
      ],
      "notes": "Includes removal of existing tub surround. Excludes permit fees."
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "estimate_id": "E-2291",
    "project_id": "84213",
    "title": "Johnson bathroom",
    "status": "draft",
    "lines": [
      {
        "name": "Demolition labor",
        "total": 968
      },
      {
        "name": "Tile",
        "total": 621
      }
    ],
    "total": 1589
  },
  "isError": false
}

Send estimate

write Confirm

MCP tool contractor-foreman_send_estimate

Emails the estimate to the recipients for online approval and e-signature. Without recipients it goes to the project customer. The client can approve it from the email. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: send_estimate
NameTypeDescription
estimate_id required string Estimate ID from create_estimate or list_estimates.
to string[] Recipient emails. Default: the project customer.
message string Email body.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_send_estimate",
    "arguments": {
      "estimate_id": "estimate_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "estimate_id": "E-2291",
    "status": "sent",
    "sent_to": [
      "client@example.com"
    ]
  },
  "isError": false
}

Create change order

write

MCP tool contractor-foreman_create_change_order

Saves a draft change order. Each line total is quantity times unit cost plus its markup, and the total is the sum of the lines. With lump_sum the client sees one total instead of the lines. Nothing reaches the client until send_change_order, so this tool runs without asking.

Parameters

Parameters: create_change_order
NameTypeDescription
project_id required string Project ID from list_projects.
title required string Change order title.
items required object Line items: name, quantity, unit cost, markup percent.
lump_sum boolean Show the client one total instead of items. Default: false.
description string Reason for the change.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_create_change_order",
    "arguments": {
      "project_id": "84213",
      "title": "Second kitchen window",
      "items": [
        {
          "name": "Window unit",
          "quantity": 1,
          "unit_cost": 780,
          "markup_percent": 20
        },
        {
          "name": "Install labor",
          "quantity": 6,
          "unit_cost": 60,
          "markup_percent": 20
        }
      ],
      "lump_sum": false,
      "description": "Client request on 9 Oct: add a second window on the kitchen east wall."
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "change_order_id": "CO-17",
    "project_id": "84213",
    "title": "Second kitchen window",
    "status": "draft",
    "lump_sum": false,
    "lines": [
      {
        "name": "Window unit",
        "total": 936
      },
      {
        "name": "Install labor",
        "total": 432
      }
    ],
    "total": 1368
  },
  "isError": false
}

Send change order

write Confirm

MCP tool contractor-foreman_send_change_order

Emails the change order to the project customer for online approval and e-signature. Approval is up to the client; the revised contract amount changes only after that. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: send_change_order
NameTypeDescription
change_order_id required string Change order ID from create_change_order.
message string Email body.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_send_change_order",
    "arguments": {
      "change_order_id": "change_order_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "change_order_id": "CO-17",
    "status": "sent",
    "sent_to": [
      "client@example.com"
    ]
  },
  "isError": false
}

Update schedule task

write

MCP tool contractor-foreman_update_schedule_task

Changes the start date, end date or percent complete of one task and returns the task as the schedule shows it afterwards. Call list_schedule_tasks again to see tasks that depend on it. A schedule edit reaches no client, and one more call undoes it, so this tool runs without asking.

Parameters

Parameters: update_schedule_task
NameTypeDescription
task_id required string Task ID from list_schedule_tasks.
start_date date New start date.
end_date date New end date.
percent_complete integer 0 to 100.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_update_schedule_task",
    "arguments": {
      "task_id": "task_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "task_id": "T-5530",
    "name": "Rough-in inspection",
    "start_date": "2026-10-16",
    "end_date": "2026-10-16",
    "percent_complete": 0
  },
  "isError": false
}

Add punchlist item

write Confirm

MCP tool contractor-foreman_add_punchlist_item

Adds a punchlist item to the project and assigns it to someone from your Directory. A due date is added to the calendar. The item is assigned to another person, so you confirm it. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: add_punchlist_item
NameTypeDescription
project_id required string Project ID from list_projects.
title required string What needs fixing.
assignee string Name or email from your Directory.
due_date date Due date, added to the calendar.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "contractor-foreman_add_punchlist_item",
    "arguments": {
      "project_id": "project_8c41d2",
      "title": "title"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "punchlist_item_id": "PL-311",
    "project_id": "84213",
    "title": "Touch up paint, hallway",
    "assignee": "Sam Rivera",
    "due_date": "2026-10-20",
    "status": "open"
  },
  "isError": false
}