@doist/todoist-ai 2.2.2 → 4.0.0

package/dist/tools/delete-object.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+declare const deleteObject: {
+    name: "delete-object";
+    description: string;
+    parameters: {
+        type: z.ZodEnum<["project", "section", "task", "comment"]>;
+        id: z.ZodString;
+    };
+    execute(args: {
+        type: "task" | "comment" | "project" | "section";
+        id: string;
+    }, client: import("@doist/todoist-api-typescript").TodoistApi): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        structuredContent: {
+            deletedEntity: {
+                type: "task" | "comment" | "project" | "section";
+                id: string;
+            };
+            success: boolean;
+        };
+    } | {
+        content: ({
+            type: "text";
+            text: string;
+            mimeType?: undefined;
+        } | {
+            type: "text";
+            mimeType: string;
+            text: string;
+        })[];
+        structuredContent?: undefined;
+    }>;
+};
+export { deleteObject };
+//# sourceMappingURL=delete-object.d.ts.map

package/dist/tools/delete-object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete-object.d.ts","sourceRoot":"","sources":["../../src/tools/delete-object.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAsBvB,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCwB,CAAA;AA+C1C,OAAO,EAAE,YAAY,EAAE,CAAA"}

package/dist/tools/delete-object.js

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { getToolOutput } from '../mcp-helpers.js';
+import { formatNextSteps } from '../utils/response-builders.js';
+import { ToolNames } from '../utils/tool-names.js';
+const { FIND_PROJECTS, GET_OVERVIEW, FIND_SECTIONS, FIND_TASKS, FIND_TASKS_BY_DATE, FIND_COMMENTS, } = ToolNames;
+const ArgsSchema = {
+    type: z
+        .enum(['project', 'section', 'task', 'comment'])
+        .describe('The type of entity to delete.'),
+    id: z.string().min(1).describe('The ID of the entity to delete.'),
+};
+const deleteObject = {
+    name: ToolNames.DELETE_OBJECT,
+    description: 'Delete a project, section, task, or comment by its ID.',
+    parameters: ArgsSchema,
+    async execute(args, client) {
+        switch (args.type) {
+            case 'project':
+                await client.deleteProject(args.id);
+                break;
+            case 'section':
+                await client.deleteSection(args.id);
+                break;
+            case 'task':
+                await client.deleteTask(args.id);
+                break;
+            case 'comment':
+                await client.deleteComment(args.id);
+                break;
+        }
+        const textContent = generateTextContent({
+            type: args.type,
+            id: args.id,
+        });
+        return getToolOutput({
+            textContent,
+            structuredContent: {
+                deletedEntity: {
+                    type: args.type,
+                    id: args.id,
+                },
+                success: true,
+            },
+        });
+    },
+};
+function generateTextContent({ type, id, }) {
+    const summary = `Deleted ${type}: id=${id}`;
+    // Recovery-focused next steps based on what was deleted
+    const nextSteps = [];
+    switch (type) {
+        case 'project':
+            // Help user understand impact and navigate remaining work
+            nextSteps.push(`Use ${FIND_PROJECTS} to see remaining projects`);
+            nextSteps.push('Note: All tasks and sections in this project were also deleted');
+            nextSteps.push(`Use ${GET_OVERVIEW} to review your updated project structure`);
+            break;
+        case 'section':
+            // Guide user to reorganize remaining sections and tasks
+            nextSteps.push(`Use ${FIND_SECTIONS} to see remaining sections in the project`);
+            nextSteps.push('Note: Tasks in this section were also deleted');
+            nextSteps.push(`Use ${FIND_TASKS} with projectId to see unorganized tasks`);
+            break;
+        case 'task':
+            // Help user stay focused on remaining work
+            nextSteps.push(`Use ${FIND_TASKS_BY_DATE} to see remaining tasks for today`);
+            nextSteps.push(`Use ${GET_OVERVIEW} to check if this affects any dependent tasks`);
+            nextSteps.push('Note: Any subtasks of this task were also deleted');
+            break;
+        case 'comment':
+            // Help user understand comment deletion impact
+            nextSteps.push(`Use ${FIND_COMMENTS} to see remaining comments on the task/project`);
+            nextSteps.push('Note: Comment attachments were also deleted');
+            break;
+    }
+    const next = formatNextSteps(nextSteps);
+    return `${summary}\n${next}`;
+}
+export { deleteObject };

package/dist/tools/find-comments.d.ts

@@ -0,0 +1,46 @@
+import type { Comment } from '@doist/todoist-api-typescript';
+import { z } from 'zod';
+declare const findComments: {
+    name: "find-comments";
+    description: string;
+    parameters: {
+        taskId: z.ZodOptional<z.ZodString>;
+        projectId: z.ZodOptional<z.ZodString>;
+        commentId: z.ZodOptional<z.ZodString>;
+        cursor: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    };
+    execute(args: {
+        projectId?: string | undefined;
+        limit?: number | undefined;
+        cursor?: string | undefined;
+        taskId?: string | undefined;
+        commentId?: string | undefined;
+    }, client: import("@doist/todoist-api-typescript").TodoistApi): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        structuredContent: {
+            comments: Comment[];
+            searchType: string;
+            searchId: string;
+            hasMore: boolean;
+            nextCursor: string | null;
+            totalCount: number;
+        };
+    } | {
+        content: ({
+            type: "text";
+            text: string;
+            mimeType?: undefined;
+        } | {
+            type: "text";
+            mimeType: string;
+            text: string;
+        })[];
+        structuredContent?: undefined;
+    }>;
+};
+export { findComments };
+//# sourceMappingURL=find-comments.d.ts.map

package/dist/tools/find-comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-comments.d.ts","sourceRoot":"","sources":["../../src/tools/find-comments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAA;AAC5D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAuBvB,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsEwB,CAAA;AAoF1C,OAAO,EAAE,YAAY,EAAE,CAAA"}

package/dist/tools/find-comments.js

@@ -0,0 +1,143 @@
+import { z } from 'zod';
+import { getToolOutput } from '../mcp-helpers.js';
+import { ApiLimits } from '../utils/constants.js';
+import { formatNextSteps } from '../utils/response-builders.js';
+import { ToolNames } from '../utils/tool-names.js';
+const { ADD_COMMENTS, UPDATE_COMMENTS, DELETE_OBJECT } = ToolNames;
+const ArgsSchema = {
+    taskId: z.string().optional().describe('Find comments for a specific task.'),
+    projectId: z.string().optional().describe('Find comments for a specific project.'),
+    commentId: z.string().optional().describe('Get a specific comment by ID.'),
+    cursor: z.string().optional().describe('Pagination cursor for retrieving more results.'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(ApiLimits.COMMENTS_MAX)
+        .optional()
+        .describe('Maximum number of comments to return'),
+};
+const findComments = {
+    name: ToolNames.FIND_COMMENTS,
+    description: 'Find comments by task, project, or get a specific comment by ID. Exactly one of taskId, projectId, or commentId must be provided.',
+    parameters: ArgsSchema,
+    async execute(args, client) {
+        // Validate that exactly one search parameter is provided
+        const searchParams = [args.taskId, args.projectId, args.commentId].filter(Boolean);
+        if (searchParams.length === 0) {
+            throw new Error('Must provide exactly one of: taskId, projectId, or commentId.');
+        }
+        if (searchParams.length > 1) {
+            throw new Error('Cannot provide multiple search parameters. Choose one of: taskId, projectId, or commentId.');
+        }
+        let comments;
+        let hasMore = false;
+        let nextCursor = null;
+        if (args.commentId) {
+            // Get single comment
+            const comment = await client.getComment(args.commentId);
+            comments = [comment];
+        }
+        else if (args.taskId) {
+            // Get comments by task
+            const response = await client.getComments({
+                taskId: args.taskId,
+                cursor: args.cursor || null,
+                limit: args.limit || ApiLimits.COMMENTS_DEFAULT,
+            });
+            comments = response.results;
+            hasMore = response.nextCursor !== null;
+            nextCursor = response.nextCursor;
+        }
+        else if (args.projectId) {
+            // Get comments by project
+            const response = await client.getComments({
+                projectId: args.projectId,
+                cursor: args.cursor || null,
+                limit: args.limit || ApiLimits.COMMENTS_DEFAULT,
+            });
+            comments = response.results;
+            hasMore = response.nextCursor !== null;
+            nextCursor = response.nextCursor;
+        }
+        else {
+            // This should never happen due to validation, but TypeScript needs it
+            throw new Error('Invalid state: no search parameter provided');
+        }
+        const textContent = generateTextContent({
+            comments,
+            searchType: args.commentId ? 'single' : args.taskId ? 'task' : 'project',
+            searchId: args.commentId || args.taskId || args.projectId || '',
+            hasMore,
+            nextCursor,
+        });
+        return getToolOutput({
+            textContent,
+            structuredContent: {
+                comments,
+                searchType: args.commentId ? 'single' : args.taskId ? 'task' : 'project',
+                searchId: args.commentId || args.taskId || args.projectId || '',
+                hasMore,
+                nextCursor,
+                totalCount: comments.length,
+            },
+        });
+    },
+};
+function generateTextContent({ comments, searchType, searchId, hasMore, nextCursor, }) {
+    if (comments.length === 0) {
+        return `No comments found for ${searchType}${searchType !== 'single' ? ` ${searchId}` : ''}`;
+    }
+    // Build summary
+    let summary;
+    if (searchType === 'single') {
+        const comment = comments[0];
+        if (!comment) {
+            return 'Comment not found';
+        }
+        const hasAttachment = comment.fileAttachment !== null;
+        const attachmentInfo = hasAttachment
+            ? ` • Has attachment: ${comment.fileAttachment?.fileName || 'file'}`
+            : '';
+        summary = `Found comment${attachmentInfo} • id=${comment.id}`;
+    }
+    else {
+        const attachmentCount = comments.filter((c) => c.fileAttachment !== null).length;
+        const attachmentInfo = attachmentCount > 0 ? ` (${attachmentCount} with attachments)` : '';
+        const commentsLabel = comments.length === 1 ? 'comment' : 'comments';
+        summary = `Found ${comments.length} ${commentsLabel} for ${searchType} ${searchId}${attachmentInfo}`;
+        if (hasMore) {
+            summary += ' • More available';
+        }
+    }
+    // Context-aware next steps
+    const nextSteps = [];
+    if (searchType === 'single') {
+        const comment = comments[0];
+        if (comment) {
+            nextSteps.push(`Use ${UPDATE_COMMENTS} with id=${comment.id} to edit content`);
+            nextSteps.push(`Use ${DELETE_OBJECT} with type=comment id=${comment.id} to remove`);
+            // Suggest viewing related comments
+            if (comment.taskId) {
+                nextSteps.push(`Use ${ToolNames.FIND_COMMENTS} with taskId=${comment.taskId} to see all task comments`);
+            }
+            else if (comment.projectId) {
+                nextSteps.push(`Use ${ToolNames.FIND_COMMENTS} with projectId=${comment.projectId} to see all project comments`);
+            }
+        }
+    }
+    else {
+        // Multiple comments
+        nextSteps.push(`Use ${ADD_COMMENTS} with ${searchType}Id=${searchId} to add new comment`);
+        if (comments.length > 0) {
+            nextSteps.push(`Use ${ToolNames.FIND_COMMENTS} with commentId to view specific comment details`);
+        }
+        // Pagination
+        if (hasMore && nextCursor) {
+            nextSteps.push(`Use ${ToolNames.FIND_COMMENTS} with cursor="${nextCursor}" to get more results`);
+        }
+    }
+    const next = formatNextSteps(nextSteps);
+    return `${summary}\n${next}`;
+}
+export { findComments };

package/dist/tools/find-completed-tasks.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+declare const findCompletedTasks: {
+    name: "find-completed-tasks";
+    description: string;
+    parameters: {
+        getBy: z.ZodDefault<z.ZodEnum<["completion", "due"]>>;
+        since: z.ZodString;
+        until: z.ZodString;
+        workspaceId: z.ZodOptional<z.ZodString>;
+        projectId: z.ZodOptional<z.ZodString>;
+        sectionId: z.ZodOptional<z.ZodString>;
+        parentId: z.ZodOptional<z.ZodString>;
+        limit: z.ZodDefault<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    };
+    execute(args: {
+        limit: number;
+        getBy: "completion" | "due";
+        since: string;
+        until: string;
+        parentId?: string | undefined;
+        workspaceId?: string | undefined;
+        projectId?: string | undefined;
+        sectionId?: string | undefined;
+        cursor?: string | undefined;
+    }, client: import("@doist/todoist-api-typescript").TodoistApi): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        structuredContent: {
+            tasks: {
+                id: string;
+                content: string;
+                description: string;
+                dueDate: string | undefined;
+                recurring: string | boolean;
+                priority: number;
+                projectId: string;
+                sectionId: string | null;
+                parentId: string | null;
+                labels: string[];
+                duration: string | null;
+            }[];
+            nextCursor: string | null;
+            totalCount: number;
+            hasMore: boolean;
+            appliedFilters: {
+                limit: number;
+                getBy: "completion" | "due";
+                since: string;
+                until: string;
+                parentId?: string | undefined;
+                workspaceId?: string | undefined;
+                projectId?: string | undefined;
+                sectionId?: string | undefined;
+                cursor?: string | undefined;
+            };
+        };
+    } | {
+        content: ({
+            type: "text";
+            text: string;
+            mimeType?: undefined;
+        } | {
+            type: "text";
+            mimeType: string;
+            text: string;
+        })[];
+        structuredContent?: undefined;
+    }>;
+};
+export { findCompletedTasks };
+//# sourceMappingURL=find-completed-tasks.d.ts.map

package/dist/tools/find-completed-tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-completed-tasks.d.ts","sourceRoot":"","sources":["../../src/tools/find-completed-tasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AA8CvB,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BkB,CAAA;AA2D1C,OAAO,EAAE,kBAAkB,EAAE,CAAA"}

package/dist/tools/find-completed-tasks.js

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { getToolOutput } from '../mcp-helpers.js';
+import { mapTask } from '../tool-helpers.js';
+import { ApiLimits } from '../utils/constants.js';
+import { previewTasks, summarizeList } from '../utils/response-builders.js';
+import { ToolNames } from '../utils/tool-names.js';
+const { FIND_TASKS_BY_DATE, GET_OVERVIEW } = ToolNames;
+const ArgsSchema = {
+    getBy: z
+        .enum(['completion', 'due'])
+        .default('completion')
+        .describe('The method to use to get the tasks: "completion" to get tasks by completion date (ie, when the task was actually completed), "due" to get tasks by due date (ie, when the task was due to be completed by).'),
+    since: z
+        .string()
+        .date()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .describe('The start date to get the tasks for. Format: YYYY-MM-DD.'),
+    until: z
+        .string()
+        .date()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .describe('The start date to get the tasks for. Format: YYYY-MM-DD.'),
+    workspaceId: z.string().optional().describe('The ID of the workspace to get the tasks for.'),
+    projectId: z.string().optional().describe('The ID of the project to get the tasks for.'),
+    sectionId: z.string().optional().describe('The ID of the section to get the tasks for.'),
+    parentId: z.string().optional().describe('The ID of the parent task to get the tasks for.'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(ApiLimits.COMPLETED_TASKS_MAX)
+        .default(ApiLimits.COMPLETED_TASKS_DEFAULT)
+        .describe('The maximum number of tasks to return.'),
+    cursor: z
+        .string()
+        .optional()
+        .describe('The cursor to get the next page of tasks (cursor is obtained from the previous call to this tool, with the same parameters).'),
+};
+const findCompletedTasks = {
+    name: ToolNames.FIND_COMPLETED_TASKS,
+    description: 'Get completed tasks.',
+    parameters: ArgsSchema,
+    async execute(args, client) {
+        const { getBy, ...rest } = args;
+        const { items, nextCursor } = getBy === 'completion'
+            ? await client.getCompletedTasksByCompletionDate(rest)
+            : await client.getCompletedTasksByDueDate(rest);
+        const mappedTasks = items.map(mapTask);
+        const textContent = generateTextContent({
+            tasks: mappedTasks,
+            args,
+            nextCursor,
+        });
+        return getToolOutput({
+            textContent,
+            structuredContent: {
+                tasks: mappedTasks,
+                nextCursor,
+                totalCount: mappedTasks.length,
+                hasMore: Boolean(nextCursor),
+                appliedFilters: args,
+            },
+        });
+    },
+};
+function generateTextContent({ tasks, args, nextCursor, }) {
+    // Generate subject description
+    const getByText = args.getBy === 'completion' ? 'completed' : 'due';
+    const subject = `Completed tasks (by ${getByText} date)`;
+    // Generate filter hints
+    const filterHints = [];
+    filterHints.push(`${getByText} date: ${args.since} to ${args.until}`);
+    if (args.projectId)
+        filterHints.push(`project: ${args.projectId}`);
+    if (args.sectionId)
+        filterHints.push(`section: ${args.sectionId}`);
+    if (args.parentId)
+        filterHints.push(`parent: ${args.parentId}`);
+    if (args.workspaceId)
+        filterHints.push(`workspace: ${args.workspaceId}`);
+    // Generate helpful suggestions for empty results
+    const zeroReasonHints = [];
+    if (tasks.length === 0) {
+        zeroReasonHints.push('No tasks completed in this date range');
+        zeroReasonHints.push('Try expanding the date range');
+        if (args.projectId || args.sectionId || args.parentId) {
+            zeroReasonHints.push('Try removing project/section/parent filters');
+        }
+        if (args.getBy === 'due') {
+            zeroReasonHints.push('Try switching to "completion" date instead');
+        }
+    }
+    // Generate contextual next steps
+    const nextSteps = [];
+    if (tasks.length > 0) {
+        nextSteps.push(`Use ${FIND_TASKS_BY_DATE} for active tasks or ${GET_OVERVIEW} for current productivity.`);
+        if (tasks.some((task) => task.recurring)) {
+            nextSteps.push('Recurring tasks will automatically create new instances.');
+        }
+    }
+    return summarizeList({
+        subject,
+        count: tasks.length,
+        limit: args.limit,
+        nextCursor: nextCursor ?? undefined,
+        filterHints,
+        previewLines: previewTasks(tasks),
+        zeroReasonHints,
+        nextSteps,
+    });
+}
+export { findCompletedTasks };

package/dist/tools/find-projects.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+declare const findProjects: {
+    name: "find-projects";
+    description: string;
+    parameters: {
+        search: z.ZodOptional<z.ZodString>;
+        limit: z.ZodDefault<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    };
+    execute(args: {
+        limit: number;
+        cursor?: string | undefined;
+        search?: string | undefined;
+    }, client: import("@doist/todoist-api-typescript").TodoistApi): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        structuredContent: {
+            projects: {
+                id: string;
+                name: string;
+                color: string;
+                isFavorite: boolean;
+                isShared: boolean;
+                parentId: string | null;
+                inboxProject: boolean;
+                viewStyle: string;
+            }[];
+            nextCursor: string | null;
+            totalCount: number;
+            hasMore: boolean;
+            appliedFilters: {
+                limit: number;
+                cursor?: string | undefined;
+                search?: string | undefined;
+            };
+        };
+    } | {
+        content: ({
+            type: "text";
+            text: string;
+            mimeType?: undefined;
+        } | {
+            type: "text";
+            mimeType: string;
+            text: string;
+        })[];
+        structuredContent?: undefined;
+    }>;
+};
+export { findProjects };
+//# sourceMappingURL=find-projects.d.ts.map

package/dist/tools/find-projects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-projects.d.ts","sourceRoot":"","sources":["../../src/tools/find-projects.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAgCvB,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BwB,CAAA;AA8D1C,OAAO,EAAE,YAAY,EAAE,CAAA"}

package/dist/tools/find-projects.js

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { getToolOutput } from '../mcp-helpers.js';
+import { mapProject } from '../tool-helpers.js';
+import { ApiLimits } from '../utils/constants.js';
+import { formatProjectPreview, summarizeList } from '../utils/response-builders.js';
+import { ToolNames } from '../utils/tool-names.js';
+const { ADD_PROJECTS, FIND_TASKS } = ToolNames;
+const ArgsSchema = {
+    search: z
+        .string()
+        .optional()
+        .describe('Search for a project by name (partial and case insensitive match). If omitted, all projects are returned.'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(ApiLimits.PROJECTS_MAX)
+        .default(ApiLimits.PROJECTS_DEFAULT)
+        .describe('The maximum number of projects to return.'),
+    cursor: z
+        .string()
+        .optional()
+        .describe('The cursor to get the next page of projects (cursor is obtained from the previous call to this tool, with the same parameters).'),
+};
+const findProjects = {
+    name: ToolNames.FIND_PROJECTS,
+    description: 'List all projects or search for projects by name. If search parameter is omitted, all projects are returned.',
+    parameters: ArgsSchema,
+    async execute(args, client) {
+        const { results, nextCursor } = await client.getProjects({
+            limit: args.limit,
+            cursor: args.cursor ?? null,
+        });
+        const searchLower = args.search ? args.search.toLowerCase() : undefined;
+        const filtered = searchLower
+            ? results.filter((project) => project.name.toLowerCase().includes(searchLower))
+            : results;
+        const projects = filtered.map(mapProject);
+        return getToolOutput({
+            textContent: generateTextContent({
+                projects,
+                args,
+                nextCursor,
+            }),
+            structuredContent: {
+                projects,
+                nextCursor,
+                totalCount: projects.length,
+                hasMore: Boolean(nextCursor),
+                appliedFilters: args,
+            },
+        });
+    },
+};
+function generateTextContent({ projects, args, nextCursor, }) {
+    // Generate subject description
+    const subject = args.search ? `Projects matching "${args.search}"` : 'Projects';
+    // Generate filter hints
+    const filterHints = [];
+    if (args.search) {
+        filterHints.push(`search: "${args.search}"`);
+    }
+    // Generate project preview lines
+    const previewLimit = 10;
+    const previewProjects = projects.slice(0, previewLimit);
+    const previewLines = previewProjects.map(formatProjectPreview).join('\n');
+    const remainingCount = projects.length - previewLimit;
+    const previewWithMore = remainingCount > 0 ? `${previewLines}\n    …and ${remainingCount} more` : previewLines;
+    // Generate helpful suggestions for empty results
+    const zeroReasonHints = [];
+    if (projects.length === 0) {
+        if (args.search) {
+            zeroReasonHints.push('Try broader search terms');
+            zeroReasonHints.push('Check spelling');
+            zeroReasonHints.push('Remove search to see all projects');
+        }
+        else {
+            zeroReasonHints.push('No projects created yet');
+            zeroReasonHints.push(`Use ${ADD_PROJECTS} to create a project`);
+        }
+    }
+    // Generate contextual next steps
+    const nextSteps = [];
+    if (projects.length > 0) {
+        nextSteps.push(`Use ${FIND_TASKS} with projectId to see tasks in specific projects.`);
+        if (projects.some((p) => p.isFavorite)) {
+            nextSteps.push('Favorite projects appear first in most Todoist views.');
+        }
+    }
+    return summarizeList({
+        subject,
+        count: projects.length,
+        limit: args.limit,
+        nextCursor: nextCursor ?? undefined,
+        filterHints,
+        previewLines: previewWithMore,
+        zeroReasonHints,
+        nextSteps,
+    });
+}
+export { findProjects };