get_due_tasks

Read-only.

The marketer’s question is “what is left to do for this event?” Reach for this tool whenever the user asks what their follow-ups are, what is overdue, or what a partner still owes. Never rebuild the queue from chat history or from rosters. Follows the heyBTW MCP rules.

When to use it

“What’s still open from the Austin dinner?”
“What’s overdue for me?”
“What does Brightpath still owe us for the open house?”
“Show me everything Tony finished last month.”

Parameters

All optional.

Parameter	Type	Required	Notes
`channel_id`	string	No	One collab, from list_events.
`event_name`	string	No	As in get_event_details. An ambiguous name returns no tasks and lists the candidates. With neither, every collab is read.
`owner`	string	No	An email for one person’s tasks, or `me` for the person behind this credential.
`status`	string	No	`open` (default: everything still owed, overdue included), `overdue`, or `completed`.
`partner_domain`	string	No	A partner on a collab you host: the tasks shared with it (status is that partner’s own assignment) and your own tasks that name its domain as an account.
`contract_version`	string	No	Omit for v1. Only v1 is advertised.

No limit and no cursor: narrow with the filters instead. At most 500 tasks are read per call; a longer queue says so in a gap.

Response

data is one row per task, ordered by due_date (undated last), then creation time, then task_id, as metadata.ordering states.

Field	Meaning
`task_id`	The id save_task takes to complete it.
`collab`	`channel_id` and `event_name`.
`title`	What will be done.
`owner_email`	Who owes it, or null when no person owns it.
`contact.contact_email`	The person it is about, or null.
`refs[]`	Accounts it references, each with `company_domain`.
`due_date`, `due_timezone`	A calendar date in the collab’s zone.
`due_gap`	Null, or why there is no due date: `no_event_date`, `no_due_offset`.
`event_window`	`pre_event`, `sprint`, `event_week`, `wind_down` or `wrapped`. Null whenever `due_gap` is set.
`status`	`open`, `overdue` or `completed`.
`provenance`	`proposed_by`, `reason`, `accepted_by`, `has_observation_ref`.
`completed_at`, `completed_by`	Set once done.
`scope`, `completion_rule`, `task_state`, `assignments[]`	Shared tasks only (`scope: "shared_collab"`). Each assignment has `partner_domain`, `partner_name`, `status` (`todo`, `in_progress`, `done`, `covered`).

A host sees every partner assigned; a partner sees only its own assignment, never the host’s own tasks, owner emails or who accepted. A real response from the heyBTW workspace’s ScaleUp.ai fixtures, trimmed to one of four rows and to the coverage notes that matter:

{
  "tool": "get_due_tasks",
  "result_count": 4,
  "data": [
    {
      "task_id": "a83ad055-a581-4f22-a43f-e0070d6f912a",
      "collab": {
        "channel_id": "cmvifxsyp000j07l2hmp06n1u",
        "event_name": "ScaleUp.ai Field Dinner: Austin"
      },
      "title": "Book the meeting with Rosa Rasmussen's CRO",
      "owner_email": "tony@heybtw.com",
      "contact": { "contact_email": "rosa.rasmussen@beaconhillsw.com" },
      "refs": [{ "type": "account", "company_domain": "beaconhillsw.com" }],
      "due_date": "2026-09-30",
      "due_timezone": "America/Chicago",
      "due_gap": null,
      "event_window": "wind_down",
      "status": "overdue",
      "provenance": {
        "proposed_by": "agent",
        "reason": "Champion. Introduced us to her CRO at the dinner.",
        "accepted_by": "ben@heybtw.com",
        "has_observation_ref": true
      },
      "completed_at": null,
      "completed_by": null
    }
  ],
  "metadata": {
    "filters_applied": { "owner": null, "status": "open" },
    "coverage_notes": [
      "A task is a commitment, not evidence of contact. This tool never reports whether anyone reached a person, and it changes and sends nothing.",
      "1 task(s) are not listed because their collab is archived. Archiving completes and deletes nothing, so they return to this queue unchanged when the collab is restored."
    ],
    "contract_version": "v1",
    "scope": { "as_of": "2026-11-03T19:36:41.812Z" },
    "ordering": "due_date_asc_nulls_last_then_created_at_asc_then_task_id_asc"
  },
  "gaps": [
    {
      "code": "partial_coverage",
      "message": "Partner events restricted by the host's Sponsor Mode",
      "retryable": false
    }
  ],
  "status": "partial"
}

Rules the agent must follow

heyBTW decides overdue, not you. A task is overdue when its due_date is before the collab’s local date at metadata.scope.as_of. Never recompute it.
Never call a task with a due_gap on time or overdue: it has no due date.
A task is a commitment, not evidence of contact. For contact use get_attendee_touch_status, and report the two as separate facts.
Tasks on an archived collab leave the open and overdue queue until it is restored; relay the coverage note that counts them.
Relay coverage_notes as written.

Errors and gaps

Code	When	What to do
`invalid_parameter`	A malformed `channel_id`, `owner`, `status` or `partner_domain`, or `owner: "me"` from a credential heyBTW cannot match to a person.	Pass the owner’s email instead of `me`.
`entity_not_found`	No collab with that `channel_id` or `event_name`.	Check list_events.
gap naming a `partner_domain`	The domain is not a partner on your collabs.	No rows; tell the user.
`partial_coverage` (not retryable)	Workspace-wide disclosure, such as partner events restricted by the host’s Sponsor Mode.	A disclosure, not a failure.
`rate_limit_exceeded`, `internal_error`		Honor Retry-After; retry once on internal_error.

A failed read is always an error, never an empty list.

save_task: create and complete tasks.
get_attendee_touch_status: whether anyone followed up.
Playbooks: Follow-up and ROI, The morning after.

Get started

How heyBTW MCP works

Playbooks

Tools: orientation

Tools: events and rosters

Tools: people and invites

Tools: after the event

Tools: accounts and partners

Tools: pipeline

When to use it

Parameters

Response

Rules the agent must follow

Errors and gaps

​When to use it

​Parameters

​Response

​Rules the agent must follow

​Errors and gaps

​Related

When to use it

Parameters

Response

Rules the agent must follow

Errors and gaps

Related