task_find_similar
Find top-K most similar existing tasks to a candidate name using lexical similarity. Use before creating a task to detect duplicates and decide whether to create, link, or merge.
Instructions
Lexical nearest-neighbour search for de-duplicating tasks. Pass a candidate name (and optional note) and receive the top-K most-similar existing tasks ranked by a deterministic [0, 1] lexical-signal score (Jaccard token-overlap + prefix bonus + exact-name boost). Title-dominant: a perfect title match outranks a perfect note match. Use BEFORE task_create when you suspect a duplicate; the agent inspects the candidates and decides whether to create new, link to existing, or merge. Excludes completed and dropped tasks by default; opt-in via includeCompleted: true. Optional scope { projectId } or { tagId } narrows the candidate set. Returns { candidates: [{ taskId, name, score, project, tags }] } sorted by score descending — project is { id, name } | null and tags is [{ id, name }, ...]. Names are paired alongside ids via a single getProjectsMany + single getTagsMany batch (no N+1) so the agent can describe each candidate without a follow-up read. An empty result is { candidates: [] }, not an error. Do NOT use this tool for general full-text search — call task_search for that. Prefer this helper when the question is 'is this task already in the system?'. No model calls; no side effects. Read-only. Example: task_find_similar({ name: "Call dentist" }) Example: task_find_similar({ name: "Write report", scope: { projectId: "prj123" }, topK: 5 })
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The candidate task name to compare against existing tasks. | |
| note | No | Optional note text. When both the candidate and an existing task have a note, note overlap contributes to the score as a tiebreaker. | |
| limit | No | Top-K candidates to return. Default 5, max 50. | |
| scope | No | Narrow the candidate set to one project or one tag. Mutually exclusive — supply at most one. Omit to search all open tasks. | |
| includeCompleted | No | When true, include completed and dropped tasks. Default false (open tasks only). |