# Task tools

> Create, read, update and comment on tasks, projects and the workspace around them.



## `get_workspace`

**Get workspace.** Read-only.

Use this when you need to know who is on the team or how work is organized: before assigning a task, when the user names a person, agent, area or project you don't know, or at the start of a session. Returns the Gorila (also spelled Gorilla) organization, its areas, its projects with open task counts, and its members (people and AI agents, each with their title, what they handle, their areas and their role in each: admin or member). What each one handles is what tells you who a piece of work goes to. Everyone is in the General area (company-wide); members see the work of their areas, owners see everything.

Parameters: none.

## `list_my_tasks`

**List my tasks.** Read-only.

Use this at the start of work, or when the user asks what to do next or what's pending. Returns the caller's open Gorila (also spelled Gorilla) tasks by status (doing, then to do; each by priority and due date), after the knowledge changes the caller has to approve or reject. Tell the user both. Tasks in doing idle 2+ days or overdue are flagged: check if done. Autonomous agents: call it on a schedule with `since` (your last check) to get only the tasks assigned to you that someone else changed since (assigned, edited, moved, or a new comment such as an answer to your question), each with what changed. Your own changes don't count. A scheduled work shift calls it with mode: shift.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `since` | `string` | no | ISO 8601 timestamp (e.g. 2026-10-22T09:00:00Z). Only tasks someone else changed or commented on after it, any status. For polling agents. |
| `mode` | `"shift"` | no | The work a person's scheduled shift may do now, in order and bounded. Agents never use it. |
| `run` | `"scheduled"` | no | Only in a scheduled work shift: "scheduled". Never in a live session. |

## `list_tasks`

**List tasks.** Read-only.

Use this when the user asks about the team's work in Gorila (also spelled Gorilla): what someone is doing, what's open in a project or area, or whether a task already exists (check before creating a duplicate). Filters by project, area, assignee (person or agent), status and text. With query it searches by meaning and words, closed tasks included: what the team already did or decided about something (before a proposal, a plan or work like past work), with the comment that closed each done task. For the caller's own tasks use list_my_tasks.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project` | `string` | no | Project name or id, from get_workspace. |
| `area` | `string` | no | Area name or id (e.g. Marketing, Support), from get_workspace. Omit when the organization has no areas or the work is company-wide. |
| `assignee` | `string` | no | Person or agent (email, @handle, name, "me"), or "unassigned". |
| `status` | `"todo" \| "doing" \| "done" \| "open" \| "any" \| "archived"` | no | todo \| doing \| done \| open (todo + doing, the default without query) \| any (every status, not archived; the default with query) \| archived (deleted tasks, which archive_task can restore). |
| `text` | `string` | no | Words in the title or context, or a task id like MAL-42. |
| `query` | `string` | no | What to look for, in a sentence or a few words, any language: "which payment provider we chose", "propuesta comercial para hoteles". Matches by meaning and words, most relevant first, done tasks with what was decided. |
| `limit` | `integer` | no |  |

## `get_task`

**Get task.** Read-only.

Use this before working on a task (then set it to doing with update_task), or when the user asks about one: returns the full task with its context (background, goal, done criteria, links), comments, history, related open tasks in the same project and what is related to it: the knowledge that applies, the closed tasks like it with the comment that closed them (decisions already taken) and what each teammate handles, to see who else it concerns.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `task_id` | `string` | yes | Task id as returned by Gorila: the short id people see on the board (like MAL-42, or just 42), or the task's UUID. |

## `create_task`

**Create task.** Changes data.

Use this when the user asks to create or delegate a task in Gorila (also spelled Gorilla), or agrees to one after mentioning work for someone ("tell Ana to…", "remind me to…"). Write the context so the assignee's AI can do it without asking: background, goal, done criteria, links; for an agent also what to return and where, its limits. Gorila refuses exact duplicates of open tasks and reviews the task first: if a red line applies or the same work is open or done in the last 30 days, it answers "Not created yet" with what to check, and confirmed: true creates it afterwards. private fits sensitive work (hiring, salaries, legal, health). get_workspace says who handles what.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | yes | Short, action-first title. |
| `context` | `string` | no | Everything the assignee needs: background, goal, done criteria, links to sources. Distilled text, never a pasted email or document. For an agent (it does exactly what the task says, and can't take a task with no context): the goal (the outcome, not the steps), done when (checks it can verify), what to return and where (the deliverable, in the done check: a document in a given folder, a draft, a pull request, a comment or a review task) and its limits (what not to touch or decide on its own). |
| `assignee` | `string` | no | Who: an email, an agent @handle, a full name, a first name, or "me". If several people match, Gorila returns the candidates instead of guessing. |
| `project` | `string` | no | Project name or id, from get_workspace. |
| `area` | `string` | no | Area name or id. Ignored when a project is given (the task takes the project's area). Left out, the task goes to the caller's own area (General if they work in several or none). |
| `priority` | `"low" \| "normal" \| "high"` | no | low \| normal \| high. |
| `due_date` | `string` | no | Due date as YYYY-MM-DD. |
| `done_check` | `string` | no | The task's deliverable, so a person, a scheduled run or an agent knows what to produce and anyone can tell it's finished: what it is, its format and where it lives, in the tools the person already uses ("Proposal as a Google Doc in /Clients/Acme", "Signed PDF in Drive › Legal", "Page in Notion under Projects", "The merged pull request"). When preparing it isn't finishing it, say both ("Draft to María in Gmail Drafts; done when it's in Sent"). With nothing to produce, whom to ask (a call, a meeting). One sentence; never the content itself. |
| `waiting_on` | `string` | no | What the task is waiting for, when its end comes after this session: "María's quote", "the merge of #63". Give recheck_at with it. Pass null once it arrived. |
| `recheck_at` | `string` | no | When to look again, as YYYY-MM-DD: from that day the person's scheduled run checks it. Pass null to clear it. |
| `prepare` | `boolean` | no | The person asks their AI to get this task ready in its scheduled run ("prepare it", "adelántalo"): research, a first draft, a comparison. Never sends anything. |
| `private` | `boolean` | no | Private: only the creator and the assignee see the task (plus the members of a private project). Use it for sensitive work. |
| `allow_duplicate` | `boolean` | no | Create it even if an open task with the same title, project and assignee exists. Only if the user explicitly wants a second identical task. |
| `confirmed` | `boolean` | no | true once Gorila answered "Not created yet" for this task and its review is settled: nothing clashes, or the user chose to create it (as is or changed). |
| `knowledge` | `string[]` | no | Ids of the knowledge entries the task follows (from the review), linked to it so whoever works on it reads them. Left out, Gorila links the red lines it found; pick the related entries that really apply. |
| `run` | `"scheduled"` | no | Only in a scheduled work shift: "scheduled". Never in a live session. |
| `shift_id` | `string` | no | With run: the shift_id that list_my_tasks (mode: shift) returned. |

## `update_task`

**Update task.** Changes data.

Use this when you or the user start working on a task (status doing), when the work is finished (status done, with a comment of what was done and links), or to reassign it or change its priority, due date, title, context, project or area. When its end comes after this session (a reply, a merge, an approval), waiting_on and recheck_at record what it waits for and when to look again. Fields left out stay as they are; null clears assignee, due_date, project or area. comment holds the reason for a non-obvious change. It works on tasks the caller created or is assigned (an area's admins: every task in it; owners: all); comment_task covers anyone else's.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `task_id` | `string` | yes | Task id as returned by Gorila: the short id people see on the board (like MAL-42, or just 42), or the task's UUID. |
| `status` | `"todo" \| "doing" \| "done"` | no | todo \| doing \| done. |
| `assignee` | `string \| null` | no | Who: an email, an agent @handle, a full name, a first name, or "me". If several people match, Gorila returns the candidates instead of guessing. |
| `priority` | `"low" \| "normal" \| "high"` | no | low \| normal \| high. |
| `due_date` | `string \| null` | no | Due date as YYYY-MM-DD. |
| `title` | `string` | no |  |
| `done_check` | `string \| null` | no | The task's deliverable, so a person, a scheduled run or an agent knows what to produce and anyone can tell it's finished: what it is, its format and where it lives, in the tools the person already uses ("Proposal as a Google Doc in /Clients/Acme", "Signed PDF in Drive › Legal", "Page in Notion under Projects", "The merged pull request"). When preparing it isn't finishing it, say both ("Draft to María in Gmail Drafts; done when it's in Sent"). With nothing to produce, whom to ask (a call, a meeting). One sentence; never the content itself. |
| `waiting_on` | `string \| null` | no | What the task is waiting for, when its end comes after this session: "María's quote", "the merge of #63". Give recheck_at with it. Pass null once it arrived. |
| `recheck_at` | `string \| null` | no | When to look again, as YYYY-MM-DD: from that day the person's scheduled run checks it. Pass null to clear it. |
| `prepare` | `boolean` | no | The person asks their AI to get this task ready in its scheduled run ("prepare it", "adelántalo"): research, a first draft, a comparison. Never sends anything. |
| `context` | `string` | no | Replaces the whole context. Read it with get_task first and keep what still applies. Assigning to an agent needs a context: the goal, done when, what to return and where, and its limits. |
| `private` | `boolean` | no | Private: only the creator and the assignee see the task (plus the members of a private project). Use it for sensitive work. |
| `project` | `string \| null` | no | Project name or id, from get_workspace. |
| `area` | `string \| null` | no | Area name or id. A task in a project always has the project's area. |
| `comment` | `string` | no | Added to the task's comments with this change (Markdown). When setting done: what you did, with links (the pull request, if any). |
| `prepared` | `true` | no | Only in a scheduled run (with run: "scheduled"): you left a draft or a first version for the person. The task shows as prepared, awaiting their review, until they act on it. |
| `run` | `"scheduled"` | no | Only in a scheduled work shift: "scheduled". Never in a live session. |
| `shift_id` | `string` | no | With run: the shift_id that list_my_tasks (mode: shift) returned. |

## `comment_task`

**Comment on task.** Changes data.

Use this to log progress, a decision, a blocker or a question on a task, so the team and the other AIs see it: after a meaningful step, when you open, merge or close a pull request for it (with its link), when you're blocked, or when you hand the task over. Commenting never changes the task's status: update_task to start or finish it. Comments are permanent; keep them short and factual.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `task_id` | `string` | yes | Task id as returned by Gorila: the short id people see on the board (like MAL-42, or just 42), or the task's UUID. |
| `body` | `string` | yes | The comment (Markdown). |
| `run` | `"scheduled"` | no | Only in a scheduled work shift: "scheduled". Never in a live session. |
| `shift_id` | `string` | no | With run: the shift_id that list_my_tasks (mode: shift) returned. |

## `archive_task`

**Archive or restore task.** Changes data.

Use this when the user asks to delete, remove or discard a task in Gorila (also spelled Gorilla): Gorila has no hard delete, so archiving is deleting. An archived task disappears from the board and the task lists but keeps its status, comments and history; restore: true brings it back as it was. Find archived tasks with list_tasks (status: archived). Archiving is not finishing: for completed work use update_task with status done. Who may change a task may archive it: its creator, its assignee, the admins of its area and owners.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `task_id` | `string` | yes | Task id as returned by Gorila: the short id people see on the board (like MAL-42, or just 42), or the task's UUID. |
| `restore` | `boolean` | no | true: bring an archived task back to the board with the status it had. |
| `reason` | `string` | no | Why, in a sentence ("duplicate of MAL-12", "no longer needed"). Added as a comment. |

## `create_project`

**Create project.** Changes data.

Use this when the user asks to start a new project (a temporary body of work with an end, like a launch or a campaign). Anyone, agents included, creates projects in the areas they are in (General when no area is given); its creator, the area's admins and owners edit it. Ongoing departments are areas, not projects. For sensitive work (hiring, compensation, legal) create it private with its members: only they see it and every task in it is private.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes |  |
| `description` | `string` | no | Goal and scope; the project's context lives here and in its tasks. |
| `area` | `string` | no | Area name or id (e.g. Marketing, Support), from get_workspace. Omit when the organization has no areas or the work is company-wide. |
| `color` | `string` | no | Hex color like #3B82F6. |
| `private` | `boolean` | no | Only its members see the project and its tasks. You are added automatically. |
| `members` | `string[]` | no | Private projects only: the other people or agents who should see it. |

## `get_task_import_plan`

**Plan bringing my tasks.** Read-only.

Use this when the user asks to bring, import or move their tasks into Gorila (also spelled Gorilla) from another tool (Notion, Linear, Jira, Asana, a to-do list, meeting notes…). It writes nothing: it answers with what to bring (only the user's own open tasks, active in the last 30 days) and what to show them before anything is written. import_my_tasks brings them after the user's yes. For one new task, use create_task.

Parameters: none.

## `import_my_tasks`

**Bring my tasks.** Changes data.

Use this when the user has seen the list of their tasks from another tool and said yes: it puts them on their board in Gorila (also spelled Gorilla), up to 30 per call. The ones Gorila already has are skipped, and the reply names what stayed out and why. get_task_import_plan says what to bring and what to show them first. Never a teammate's tasks: each person brings their own. For one new task, use create_task.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `tasks` | `object[]` | yes | The user's own open tasks they agreed to bring, at most 30 per call. |
| `tasks_left_out` | `object` | no | How many tasks you saw in the sources and did not send, as you told the user. Gorila repeats them in its final answer so the user sees what stayed out and why: send the same counts with every batch. |
