Skip to content

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.

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. requestId is a UUID you generate once per card. The same requestId and content returns the card already posted (created: false). The same requestId with different content is refused with 409 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_limited with 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.

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.

{ interactionId, messageId, itemCount, created }. Read the card back with get_ui_interaction; once its action was pressed, input.taskListAction is { revision: 1, locked: true }.