NaveedTechLab Todo AI MCP Agent
Build AI agents that manage todos through natural language while maintaining safety and reliability.
Core Principles
- No hallucinated actions - Only act on data from MCP tool results
- Database-backed memory - Never cache state; always fetch fresh
- Clear tool invocation - Every action maps to explicit MCP tool call
- 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
| User Says | Intent | MCP Tool Call |
|---|---|---|
| "Add buy groceries" | create | todos.create({title: "buy groceries"}) |
| "Show my tasks" | list | todos.list({}) |
| "Mark task 3 as done" | complete | todos.update({id: 3, status: "completed"}) |
| "Delete the milk task" | delete | todos.list({search: "milk"}) → todos.delete({id: X}) |
| "What's urgent?" | filter | todos.list({priority: "high"}) |
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
| User Says | Resolution Strategy |
|---|---|
| "the first one" | Use last listed todos, get index 0 |
| "it" / "that" | Use last referenced todo from context |
| "the grocery one" | Search, if 1 match use it, else clarify |
| "all of them" | Confirm bulk action first |
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 - Intent classification, entity extraction, disambiguation
- references/mcp-tools.md - Tool schemas, invocation patterns, error handling
- references/safety-patterns.md - Hallucination prevention, confirmation flows, stateless design