feat: Improve tool output UX with LLM-readable responses

[gnapse]

🗺️ Overview

Implements more human and LLM-readable responses for all Todoist AI tools using MCP dual content format. Tools now provide both contextual text summaries and structured content, improving LLM comprehension and user experience.

• Closes Improve tool output UX with LLM/human-readable responses #48
• https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-result

🧩 Problem

Tools returned only structured JSON, forcing LLMs to interpret raw data without context:

• Poor LLM comprehension of operation outcomes
• No actionable next-step suggestions
• Missing workflow guidance

💡 Solution

1. Response builders (src/utils/response-builders.ts) - Task summaries, batch operations, list formatting, next-step suggestions
2. MCP dual format (src/mcp-helpers.ts) - Text + structured content via new getToolOutput() function
3. All 13 tools migrated with human-readable summaries and preserved or improved structured data

🌟 Benefits

• Enhanced LLM comprehension with explicit context
• Better user assistance via contextual suggestions
• MCP specification compliance
• Backwards compatibility maintained
  • The new structured content is sent serialized as JSON in the content part for now
  • The newer structuredContent field from the more recent June 18th MCP spec is hidden for now, controlled by an environment variable.

🧪 Test plan

These instructions are specific for Claude Desktop, but you should be able to adapt them for Claude Code or Cursor or VS Code by searching the web to see where their MCP config file can be found.

1. Clone this repository
2. Run npm install && npm run build
3. Set it up in Claude Desktop's MCP json configuration:
   • Find it in Claude Desktop settings > Developer > Edit Config
   • or find it in /Users/<username>/Library/Application Support/Claude/claude_desktop_config.json in macOS
   • add this todoist-ai-local entry under the mcpServers object

     {
         "mcpServers": {
             "todoist-ai-local": {
                 "command": "node",
                 "args": ["/path/to/todoist-ai/dist/main.js"], // change this path ⚠️
                 "env": {
                     "TODOIST_API_KEY": "<PRODUCTION-API-KEY>" // change this API key ⚠️
                 }
             }
         }
     }

   • ⚠️ Make sure to put the right path to your dist/main.js file, and a valid production API key for Todoist
4. Open Claude Desktop and enjoy

🎥 Demo

CleanShot.2025-08-19.at.15.21.37.mp4

🌐 Usage in other languages

I was worried about the natural language response being in English, and what would happen if we used this when chatting with the LLM in a language other than English. So I tried, and it seems to work well.

👉 Here's a demo and a screenshot:

(click to expand)

CleanShot.2025-08-19.at.15.37.59.mp4

I even asked the LLM if it received some suggestions for actions that could come next, and it totally got it from the English language response, but answered me in Spanish about it:

[Copilot]

Pull Request Overview

This PR implements human-readable responses for all Todoist AI tools using MCP dual content format, providing both contextual text summaries and structured content to improve LLM comprehension and user experience.

• MCP dual format implementation - New getToolOutput() function provides both text and structured content
• Response builders module - Centralized utilities for task summaries, batch operations, list formatting, and next-step suggestions
• Tool name centralization - Single source of truth for tool names to prevent outdated references

Reviewed Changes

Copilot reviewed 41 out of 41 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/utils/tool-names.ts	Centralized tool names constants to prevent hardcoded strings
src/utils/response-builders.ts	Response formatting utilities for task operations, lists, and contextual guidance
src/tools/test-helpers.ts	Test utilities including text content extraction and fixed date constants
src/tools/tasks-*.ts	Updated task tools to use dual format with human-readable summaries
src/tools/sections-*.ts	Updated section tools with contextual text responses
src/tools/projects-*.ts	Updated project tools with workflow-aware next steps
src/tools/overview.ts	Updated overview tool to provide both markdown and structured data
src/tools/delete-one.ts	Updated delete tool with recovery-focused guidance
src/tools/__tests__/**	Updated tests to validate text content using snapshots
src/mcp-helpers.ts	Simplified MCP helpers with new dual format function

Comments suppressed due to low confidence (2)

src/utils/response-builders.ts:83

• Consider moving the new Date() call outside the loop to avoid creating a new Date object for each task comparison. Store it in a variable like const now = new Date() before the some() call.

}

src/utils/response-builders.ts:284

• The new Date().toISOString().split('T')[0] expression is computed for each task. Consider extracting this to a variable like const today = new Date().toISOString().split('T')[0] before the some() call.

            }

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}