Show tasks in a list
When your agent has tasks to show (from monday, HubSpot or any tracker), post them as a task list instead of text. People scroll the list or table, tick tasks and open links. The tool is show_task_list, part of the Streams MCP server.
What the tool does
Section titled “What the tool does”show_task_list posts one card as a message from your agent, with a one-line text caption for readers that cannot render the card (older apps, search, push notifications): <Agent> shared a task list: <heading> (<N> tasks).
- A snapshot. The card never loads more tasks and never refreshes. Fetch the tasks first and send what you want shown.
- Display only. Nothing comes back unless you add an action and a person presses it. The call returns at once and viewing the card never starts a turn. Ticks are each viewer’s own and are lost on reload.
- Everyone in the session sees the tasks. Only post a list where the person agreed to share it with that audience.
- All or nothing. If anything is invalid, nothing is posted and the error lists each problem with the path of the field to fix.
- Safe to retry.
requestIdis a UUID you generate once per card. The samerequestIdand content returns the card already posted (created: false). The samerequestIdwith different content is refused with409 chat.task_list_request_conflict, and so is a retry after the card’s message was deleted. - Rate limit. At most 5 new cards per minute per stream and agent:
429 chat.task_list_rate_limitedwith the seconds to wait. Retries do not count.
| Field | Type | Notes |
|---|---|---|
requestId |
UUID | Generate once per card; reuse it on a retry. |
streamId |
UUID | The stream to post in. Your agent must be a member. |
threadSessionId, replyToMessageId |
UUID, optional | Put the card in that thread. With both, they must name the same thread. |
heading |
string | The card title, up to 80 characters. |
source |
object, optional | { label, url? }, where the tasks came from. An HTTPS url opens it. |
items |
array | Up to 50 tasks: { id, title, sourceId?, url?, groupId?, cells? }. |
columns |
array, optional | Up to 4: { id, label, type }. Three or more columns make a table. |
groups |
array, optional | Up to 10: { id, label }. Either every item has a groupId or none does. |
marker |
string, optional | checkbox (the default, people can tick), number or bullet. |
initialVisibleCount |
number, optional | 1 to 10 rows before “Show more”. |
action |
object, optional | { label, prompt }: one button, see below. |
state, empty, error |
optional | ready (the default) or error, with { title, description? } messages. |
labels |
object, optional | Plain strings that replace the card’s English text. |
id values are lowercase slugs (letters, digits, - or _, at most 40 characters) and unique. The whole input is at most 64 KiB. A cell is one of status, person, date, timeline, number, progress, tags, checkbox, link or text, and must match its column’s type:
| Type | Cell |
|---|---|
status |
{ type, label, color } |
person |
{ type, people: [{ name, initials? }] } |
date |
{ type, date: "YYYY-MM-DD", overdue? } |
timeline |
{ type, from, to } |
number |
{ type, value, unit?, unitPosition? } |
progress |
{ type, value: 0 to 100 } |
tags |
{ type, tags: [{ label, color? }] } |
checkbox |
{ type, checked } |
link |
{ type, label, url } |
text |
{ type, text } |
Colors are blue, purple, green, orange, red, pink, teal or gray. Only HTTPS and HTTP links without credentials are ever opened.
The action button
Section titled “The action button”action adds one button to the card. When a person presses it, Streams posts a normal message from them in the card’s thread: your prompt, the tasks they ticked (title and sourceId) and a mention of your agent (no mention in a one-to-one DM). The first press wins for the whole card, and the button locks for everyone. Write prompt as the instruction you want to receive, for example “Mark the selected tasks as done.” Use an action only when you can act on the ticked tasks.
Result
Section titled “Result”{ interactionId, messageId, itemCount, created }. Read the card back with get_ui_interaction; once its action was pressed, input.taskListAction is { revision: 1, locked: true }.