Skip to main content
Glama

List To Do Tasks

list_todo_tasks
Read-only

Lists Microsoft To Do tasks in a specified list and tracks changes since a prior call using a delta token, returning added, modified, or removed tasks.

Instructions

List tasks in a To Do list, or what changed in it since your last call. For changes, call once with delta: true, which returns every task and a 'Delta token: …' line; keep the token and pass it as delta_token next time to get only the tasks added, changed or removed since (removed ones as 'Removed: ()' lines), and a new token. Completing a repeating task makes Graph keep the series and split off the finished occurrence as a new, already-completed task with a new id, so an unseen completed task is a done occurrence, not new work. Your own writes come back as changes too. The Flagged Emails list (wellknownListName flaggedEmails) holds the emails flagged in Outlook; each of its tasks carries (Mail: ), the id the mail tools use, when its Outlook link parses

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "list_id": "<list_id>"
    },
    "name": "list_todo_tasks"
  }
}

Input Schema

NameRequiredDescriptionDefault
deltaNoStart a change feed: return every task and a first delta token. Always reads every page
list_idYesTo Do list ID. A delta token works only with the list it came from
delta_tokenNoThe token from the last 'Delta token: …' line. Returns only what changed since. If the token is refused, start again with delta: true
extension_nameNoPrint this extension's fields at the end of each task line, as (Ext: {...}). With a change feed, only calls with a delta_token can include them
fetch_all_pagesNoFetch all pages of results (max 50 pages)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, which covers the safety profile, and the description adds substantial context beyond that: delta token lifecycle, 'Removed: <id> (<reason>)' lines, own writes appearing as changes, and the repeating-task split behavior. That is meaningful added context, but combined with the annotation the disclosure is strong rather than exceptional. Returns are described qualitatively but not as a schema, which the lack of output schema makes acceptable here.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core capability and the delta workflow are front-loaded in the first two sentences, with edge cases (repeating tasks, flagged emails) afterwards. The prose is dense and runs long in a single block, and details like the Graph repeating-task mechanics are useful but could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, yet the description conveys the return shape: task lines, a literal 'Delta token: …' line, and 'Removed: <id> (<reason>)' markers, plus the (Mail: <message id>) and (Ext: {...}) annotations on lines. For a read-only list tool with five well-documented parameters, an agent has everything needed to call it and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description nevertheless adds semantics the schema only hints at, notably that a delta token is bound to the list it came from ('keep the token and pass it as delta_token next time') and that extension_name is only usable with a delta_token during a change feed. It clarifies the coupling between parameters rather than merely restating them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('List tasks in a To Do list') and immediately names the second mode ('what changed in it since your last call'). The 'To Do list' scoping plus mention of flaggedEmails and delta distinguishes it from sibling listers such as list_planner_tasks without needing the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit mode-selection guidance: use the plain call for a full listing, and 'call once with delta: true' then pass delta_token for changes. It also explains recovery from a refused token ('start again with delta: true'). It does not name an alternative tool for listing tasks elsewhere (e.g. Planner), so it stops short of full when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools