MCP Todo Tools With a Narrow Write Surface

The Temptation

When you add tasks to an MCP surface, the obvious temptation is to ship full CRUD immediately:

• create
• update
• delete
• bulk import
• multiple lists
• subtasks

That sounds powerful. It is also how you create a misleading product.

At the time of this design, the existing /todos page was still browser-local. So if we had pretended the agent could fully manage "the same todo system," we would have been lying to users.

Update: the product has since moved task operations into /tasks, with /inbox focused on human review. The legacy /todos path now points users toward that newer operating model.

The Constraint We Refused to Hide

The honest architecture looked like this:

• the connected agent needed a real remote todo store
• the web UI at the time was not yet backed by that store
• the agent should still be useful today
• the tool surface should not imply capabilities the product could not safely support

That led to a simple conclusion: stay read-first, then add one narrow write path.

The Tool Surface We Chose

We kept the first phase intentionally small:

• get_todo_list
• create_todo

We did not add:

• update_todo
• delete_todo
• bulk task creation
• subtasks
• multiple named lists

Why? Because each extra mutation path increases the chance that an agent does something surprising, duplicates work, or creates a false sense of synchronization with the current web page.

The Guardrails That Matter

The write path was designed to be selective, not general.

Single-item create only

The agent can create exactly one task at a time. That keeps side effects legible and reviewable.

Duplicate protection

If an active matching task already exists, the system reuses it instead of creating another copy. This sounds small, but it prevents a very common failure mode in agent systems: quiet duplication.

Explicit provenance

Tasks created by the agent are marked with created_via = 'agent_mcp'. That gives the future UI a clean way to label, filter, or audit agent-created work.

Honest boundary language

The tool contract explicitly noted the remote MCP todo store was not yet the same source of truth as the then-current /todos page. That boundary language mattered because users needed to know what was safe to trust before the Tasks board became the canonical UI.

Why Reusing the Existing MCP Path Was Important

We did not add a second bridge or a one-off backend. The todo tools extend the same token-gated MCP path already used elsewhere in 6DuckLearn.

That means:

• the auth model stays consistent
• the discovery model stays consistent
• the agent remains user-scoped
• the platform does not grow a second shadow integration surface

The Design Principle

A tool can be narrow and still be valuable.

In fact, when agents are involved, narrow is often more trustworthy than broad.

The bad version of this feature would have looked more impressive in a demo. It also would have been harder to reason about, easier to misuse, and less honest about the current product boundary.

So we picked the smaller surface on purpose. The point was not to maximize commands. The point was to create a tool the user could actually trust.

Proof Level and Limitations

• Proof level: Internal workflow and MCP surface case study.
• What this demonstrates: A read-first agent tool with one narrow create path can reduce accidental side effects while still being useful.
• What this does not claim: It does not claim full task synchronization, bulk task management, or autonomous task execution without user review.
• Source anchors: MCP todo tools, /tasks, /inbox, duplicate protection, and created_via = 'agent_mcp' provenance.