todoist-mcp: Instructions file for Codex

Todoist MCP Server - Development Guidelines

Tool Schema Design Rules

Removing/Clearing Optional Fields

When you need to support clearing an optional field:

1. Use a special string value (not null - avoids LLM provider compatibility issues, with Gemini in particular)

   • For assignments: use "unassign"
   • For other fields: use "remove" or similar descriptive string

2. Handle both legacy and new patterns in runtime logic for backward compatibility:

   if (fieldValue === null || fieldValue === 'remove') {
       // Convert to null for API call
       updateArgs = { ...updateArgs, fieldName: null }
   }
   

3. Update schema description to document the special string value

Examples from Codebase

• PR #181: Fixed responsibleUser field - changed from .nullable() to using "unassign" string
• Latest commit: Fixed deadlineDate field - changed from .nullable() to using "remove" string

Why This Matters

• Ensures compatibility with all LLM providers (OpenAI, Anthropic, Gemini, etc.)
• Maintains backward compatibility through dual handling
• Creates self-documenting APIs with explicit action strings

Describing output schema fields

Every tool's outputSchema is sent to clients on every tools/list, and the shared schemas in src/utils/output-schemas.ts are inlined once per tool that uses them — so a description on TaskSchema.id is paid eight times over.

Describe an output field only where the schema cannot express the thing itself:

• units or formats — 'ISO 8601.', 'Bytes.', 'e.g. "2h30m".'
• conventions that are not derivable — priority: 'p1 is highest, p4 lowest.'
• unions — recurring: 'False when not recurring, otherwise the recurrence string.'
• conditional presence — workspaceId: 'Undefined for personal projects.'
• non-obvious meaning — isUncompletable: 'An organizational header, not a real task.'

Leave it off when the description would restate the field name (id, projectId, name), or list values an enum already carries. Note this is the output side only: input field descriptions are how a model learns to call the tool correctly and should stay as full as they need to be.