Todo AI MCP Agent

Build AI agents that manage todos through natural language while maintaining safety and reliability.

Core Principles

1. No hallucinated actions - Only act on data from MCP tool results
2. Database-backed memory - Never cache state; always fetch fresh
3. Clear tool invocation - Every action maps to explicit MCP tool call
4. Stateless server - Session context only; no persistent agent state

Agent Flow

User Input
    │
    ▼
┌─────────────────┐
│ Parse Intent    │ ← "Add buy milk" → intent: create, title: "buy milk"
└─────────────────┘
    │
    ▼
┌─────────────────┐
│ Validate/Clarify│ ← Ambiguous? Ask user
└─────────────────┘
    │
    ▼
┌─────────────────┐
│ Invoke MCP Tool │ ← todos.create({title: "buy milk"})
└─────────────────┘
    │
    ▼
┌─────────────────┐
│ Format Response │ ← "Created 'buy milk'"
└─────────────────┘

Intent to Tool Mapping

MCP Tools

todos.list

{
  "status": "pending|completed|archived",
  "priority": "low|medium|high",
  "search": "text to match",
  "limit": 20
}

todos.create

{
  "title": "required string",
  "description": "optional",
  "priority": "low|medium|high",
  "due_date": "ISO 8601 datetime"
}

todos.update

{
  "id": "required integer",
  "title": "optional new title",
  "status": "pending|completed|archived",
  "priority": "low|medium|high"
}

todos.delete

{
  "id": "required integer"
}

Safety Rules

Never Invent Data

# WRONG - Making up todos
"You have: buy milk, call mom"  # Hallucinated!

# RIGHT - Use tool result
result = await mcp.call_tool("todos.list", {})
response = format_todos(result)  # From actual data

Always Verify Before Acting

# WRONG - Assuming ID
await mcp.call_tool("todos.delete", {"id": 1})

# RIGHT - Search first
todos = await mcp.call_tool("todos.list", {"search": "milk"})
if len(todos) == 1:
    await mcp.call_tool("todos.delete", {"id": todos[0]["id"]})
elif len(todos) > 1:
    ask_user_to_clarify(todos)
else:
    report_not_found()

Confirm Destructive Actions

NEEDS_CONFIRMATION = ["delete", "bulk_delete", "clear_all"]

if action in NEEDS_CONFIRMATION:
    return f"Delete '{todo.title}'? This cannot be undone. (yes/no)"

Handling Ambiguity

Reference Resolution

Clarification Pattern

if matches == 0:
    "I couldn't find a todo matching 'X'. Show your list?"
elif matches > 1:
    "Found {n} todos matching 'X'. Which one?\n{list}"
else:
    proceed_with_action()

Response Patterns

Successful Actions

Created: "Created 'buy milk'"
Listed:  "You have 3 todos:\n- buy milk\n- call mom\n- finish report"
Updated: "Marked 'buy milk' as complete"
Deleted: "Deleted 'buy milk'"

Errors

Not found:  "I couldn't find that todo. Would you like to see your list?"
Validation: "Title can't be empty. What should I call this todo?"
Conflict:   "That todo was just modified. Current status: completed"

Session Context (Non-Persistent)

class SessionContext:
    last_listed_todos: list[Todo]  # For "the first one"
    last_referenced_todo: Todo     # For "it" / "that"
    pending_confirmation: Action   # Awaiting yes/no

# Lives only in session memory
# NOT stored in database
# Expires with conversation

Multi-Action Handling

User: "Add buy milk and complete the groceries task"

# Parse multiple intents
intents = [
    {"action": "create", "title": "buy milk"},
    {"action": "complete", "search": "groceries"},
]

# Execute sequentially
results = []
for intent in intents:
    result = await execute_intent(intent)
    results.append(result)

# Compose response
"Created 'buy milk' and completed 'groceries'"

References

• [references/intent-mapping.md](references/intent-mapping.md) - Intent classification, entity extraction, disambiguation
• [references/mcp-tools.md](references/mcp-tools.md) - Tool schemas, invocation patterns, error handling
• [references/safety-patterns.md](references/safety-patterns.md) - Hallucination prevention, confirmation flows, stateless design