# Tool reference

> Generated by `npm run api-docs` from `lib/tools.js` — do not edit by hand. 75 tools.

Badges: `RO` read-only (`readOnlyHint: true`) · `W` write · `DESTRUCTIVE` requires `confirm: true` and carries `destructiveHint`. Every tool declares MCP annotations, so clients that understand them can auto-allow reads and gate writes.

## Reads (26)

### `asana_find_duplicates` `RO`

Find TRUE duplicate tasks. Dedupes by GID FIRST — one task on N boards = multi_homed (shared membership, reported separately, NOT a dup; deleting it removes the real task from EVERY board) — then groups DISTINCT gids by name. Scan one project/section, or projects[] for cross-board. Returns {multi_homed, true_duplicate_clusters}. Read-only — reason before you delete.

Params: `project` · `projects` · `section` · `include_completed` · `max_pages`

### `asana_get_custom_field` `RO`

Fetch one custom field by GID — type, precision, and full enum_options (name+GID) list.

Params: `custom_field_gid`* · `opt_fields`

### `asana_get_custom_field_settings` `RO`

Fetch a project's custom field settings — live field GIDs, types, and enum option GIDs. Use this to derive field/option GIDs live instead of trusting hand-coded maps that drift.

Params: `project_gid`* · `opt_fields` · `limit` · `max_pages`

### `asana_get_job` `RO`

Poll an async job by GID (from duplicate_task/duplicate_project/instantiate_* tools). Returns status (not_started|in_progress|succeeded|failed) and the new_task/new_project GID once done.

Params: `job_gid`* · `opt_fields`

### `asana_get_portfolio` `RO`

Fetch one portfolio; set include_items=true to also pull its member projects/portfolios.

Params: `portfolio_gid`* · `include_items` · `opt_fields`

### `asana_get_project` `RO`

Fetch one project with its custom_field_settings (field GIDs + enum option GIDs) AND its sections, merged into one response.

Params: `project_gid`* · `opt_fields`

### `asana_get_task` `RO`

Fetch one task with rich fields (assignee, projects, section memberships, custom fields, notes, subtask count). Override opt_fields for more/less.

Params: `task_gid`* · `opt_fields`

### `asana_get_user` `RO`

Fetch one user by GID (default "me" = token owner). Returns name, email, GID.

Params: `user_gid` · `opt_fields`

### `asana_get_workspace` `RO`

Fetch workspace metadata (name, is_organization, email_domains).

Params: `workspace` · `opt_fields`

### `asana_list_attachments` `RO`

List a task's attachments with download/permanent URLs and sizes.

Params: `task_gid`* · `opt_fields` · `limit` · `max_pages`

### `asana_list_dependencies` `RO`

Return a task's dependencies (what it waits on) AND dependents (what waits on it), in one call.

Params: `task_gid`*

### `asana_list_portfolios` `RO`

List portfolios owned by a user in the workspace. owner defaults to "me". Paginated.

Params: `workspace` · `owner` · `opt_fields` · `limit` · `max_pages`

### `asana_list_project_statuses` `RO`

List a project's status updates (status_type, title, text, author). Paginated.

Params: `project_gid`* · `opt_fields` · `limit` · `max_pages`

### `asana_list_projects` `RO`

List projects in the workspace (or a team). Excludes archived by default; set include_archived=true for all. Paginated.

Params: `workspace` · `team` · `include_archived` · `opt_fields` · `limit` · `max_pages`

### `asana_list_sections` `RO`

List the sections of a project (name + GID), in board order.

Params: `project_gid`* · `opt_fields`

### `asana_list_stories` `RO`

List a task's stories (comments + activity log). text field holds comment bodies. Paginated.

Params: `task_gid`* · `opt_fields` · `limit` · `max_pages`

### `asana_list_subtasks` `RO`

List a task's subtasks with rich fields. Paginated.

Params: `task_gid`* · `opt_fields` · `limit` · `max_pages`

### `asana_list_tags` `RO`

List tags in the workspace (name → GID). Paginated.

Params: `workspace` · `opt_fields` · `limit` · `max_pages`

### `asana_list_task_templates` `RO`

List a project's task templates (repeatable task blueprints). Paginated.

Params: `project_gid`* · `opt_fields` · `limit` · `max_pages`

### `asana_list_tasks` `RO`

List tasks by project, section, tag, OR assignee (provide exactly one anchor). Paginated. assignee uses the workspace default.

Params: `project` · `section` · `tag` · `assignee` · `workspace` · `completed_since` · `opt_fields` · `limit` · `max_pages`

### `asana_list_teams` `RO`

List teams the token owner belongs to in the workspace/organization. Paginated.

Params: `workspace` · `opt_fields` · `limit` · `max_pages`

### `asana_list_users` `RO`

List workspace members (name → GID resolution). Paginated.

Params: `workspace` · `opt_fields` · `limit` · `max_pages`

### `asana_list_workspace_custom_fields` `RO`

List ALL custom fields defined in the workspace (design discovery — find a field GID to attach to a board). Paginated.

Params: `workspace` · `opt_fields` · `limit` · `max_pages`

### `asana_my_tasks` `RO`

List the TOKEN OWNER's My Tasks (user task list). NOTE: a personal PAT can only read its OWN My Tasks — passing another user returns 403. For other users use asana_search_tasks or asana_list_tasks with assignee=<gid>, or asana_user_queue. Paginated.

Params: `user` · `workspace` · `completed_since` · `opt_fields` · `limit` · `max_pages`

### `asana_search_tasks` `RO`

Advanced workspace task search with filters: text, assignee, project, section, tag, completed, due/created date ranges, custom-field filters (filters passthrough), sorting. Single page (search API caps at 100, no offset).

Params: `text` · `assignee` · `project` · `section` · `tag` · `completed` · `due_before` · `due_after` · `created_before` · `created_after` · `filters` · `sort_by` · `sort_ascending` · `workspace` · `limit` · `opt_fields`

### `asana_typeahead` `RO`

Resolve a partial NAME → GID across the workspace for any resource type (task|project|user|tag|portfolio|project_template|goal). Fast lookup when you do not know the GID.

Params: `query`* · `resource_type` · `workspace` · `count` · `opt_fields`


## Composites (one call, one answer) (5)

### `asana_board_rollup` `RO`

COMPOSITE: roll up ONE board (project) — active tasks grouped by section, an amount custom field summed per section and in total (e.g. "Deal $", "Claim $"), an optional secondary amount, and every task whose deadline (any named date custom fields + due_on) has passed, with days overdue and WHICH field fired. Ranked by amount descending. Fields may be given by GID or by exact name (resolved live via the project's custom_field_settings, so nothing is hard-coded).

Params: `project_gid`* · `amount_field` · `secondary_amount_field` · `deadline_fields` · `status_field` · `include_completed` · `max_pages`

### `asana_morning_brief` `RO`

COMPOSITE: one-call daily brief — incomplete tasks bucketed into overdue / due_today / upcoming (within horizon_days) + blocked (due-window tasks waiting on an incomplete dependency), with a summary count. Defaults to "me"; pass user=<gid> for a teammate or user="all" for the whole workspace. Built on the search API (caps at 100 by due date).

Params: `user` · `horizon_days` · `workspace`

### `asana_portfolio_rollup` `RO`

COMPOSITE: per-project health across a portfolio — incomplete, overdue, and completed-in-window counts + current status, sorted by overdue. Scope via projects:[gids] (best), portfolio_gid, or default to all non-archived workspace projects (capped at max_projects). One task-list call per project; caps are reported, never silent.

Params: `projects` · `portfolio_gid` · `window_days` · `max_projects` · `workspace`

### `asana_triage_inbox` `W`

COMPOSITE: bulk-create tasks from a triaged list in ONE call (fills the gap — no bulk CREATE existed). The model reads the inbox/note, extracts items, and passes them here. Per-item project/assignee/section/due override the defaults; default_assignee falls back to ASANA_DEFAULT_ASSIGNEE, else "me". Continues past individual failures; returns a per-item created/failed summary with permalinks.

Params: `items`* · `default_assignee` · `default_project` · `default_section` · `workspace`

### `asana_user_queue` `RO`

COMPOSITE: one person's FULL incomplete queue — paginated (NOT capped at 100 like the search API), bucketed by due (overdue / due_today / this_week / later / no_due) with a per-project count map. Default user = "me"; pass user=<gid> for a teammate (the PAT-owner-only restriction on My Tasks does not apply — this uses /tasks?assignee=). The right call for "what is X sitting on?" and hand-off reviews.

Params: `user` · `workspace` · `max_pages`


## Writes (41)

### `asana_add_comment` `W`

Add a comment (story) to a task. Prefer text (plain, with real newlines; literal "\n" sequences are auto-converted) — the /stories endpoint escapes html_text into literal tags. Pass html_text only if you accept that.

Params: `task_gid`* · `text` · `html_text`

### `asana_add_dependency` `W`

Mark a task as depending on one or more other tasks (this task waits on them).

Params: `task_gid`* · `depends_on`*

### `asana_add_dependent` `W`

Mark one or more tasks as dependent on this task (they wait on this one).

Params: `task_gid`* · `dependent`*

### `asana_add_enum_option` `W`

Add an option to an existing enum/multi_enum custom field (extend a dropdown without recreating the field).

Params: `custom_field_gid`* · `name`* · `color` · `insert_before` · `insert_after`

### `asana_add_field_to_project` `W`

Attach an existing custom field to a project (addCustomFieldSetting), optionally important/positioned. Pairs with asana_create_custom_field to build a board.

Params: `project_gid`* · `custom_field_gid`* · `is_important` · `insert_before` · `insert_after`

### `asana_add_follower` `W`

Add follower(s) to a task.

Params: `task_gid`* · `followers`*

### `asana_add_project_members` `W`

Add member(s) to a project (e.g. add a teammate to a new board).

Params: `project_gid`* · `members`*

### `asana_add_tag` `W`

Add a tag to a task.

Params: `task_gid`* · `tag_gid`*

### `asana_add_to_portfolio` `W`

Add a project/portfolio item to a portfolio.

Params: `portfolio_gid`* · `item_gid`*

### `asana_add_to_project` `W`

Add a task to a project, optionally placing it in a specific section. Fixes: no MCP tool for addProject + section placement.

Params: `task_gid`* · `project_gid`* · `section_gid`

### `asana_attach_file` `W`

Attach a local file to an Asana task. Requires confirm:true and restricts reads to the current directory or ASANA_MCP_FILE_ROOTS. Max 100MB.

Params: `task_gid`* · `file_path`* · `file_name` · `confirm`

### `asana_batch_ops` `W`

Execute up to 5 Asana API operations in a single HTTP call. ⚠ GET-with-default-fields ONLY — options (opt_fields/completed_since) + PUT data are dropped by the batch endpoint. For filtered reads use asana_search_tasks/asana_list_*; for writes use the dedicated tools.

Params: `actions`*

### `asana_batch_update` `W`

Update multiple task fields in a single REST call. Combines assignee, dates, custom fields, notes, name, and completion.

Params: `task_gid`* · `name` · `assignee` · `due_on` · `start_on` · `notes` · `html_notes` · `custom_fields` · `completed`

### `asana_bulk_move_section` `W`

Move MANY tasks into one section in a single call (loops section addTask). Returns a per-task summary. Throughput multiplier for triaging a board column.

Params: `task_gids`* · `section_gid`*

### `asana_bulk_update` `W`

Apply the SAME field changes to MANY tasks in one call (assignee, dates, completed, notes/html_notes, custom_fields). Loops PUT per task, continues past individual failures, returns a per-task summary.

Params: `task_gids`* · `assignee` · `due_on` · `start_on` · `completed` · `notes` · `html_notes` · `custom_fields`

### `asana_complete_task` `W`

Mark a task complete (default) or incomplete (completed:false).

Params: `task_gid`* · `completed`

### `asana_create_custom_field` `W`

Create a workspace custom field (design the board schema). resource_subtype ∈ text|number|enum|multi_enum|date|people. For enum/multi_enum pass enum_options:[{name,color?}].

Params: `name`* · `resource_subtype`* · `workspace` · `enum_options` · `precision` · `description`

### `asana_create_portfolio` `W`

Create a portfolio (group projects for North-Star-style tracking).

Params: `name`* · `workspace` · `color`

### `asana_create_project` `W`

Create a project. In an org workspace a team GID is required; otherwise the workspace default is used.

Params: `name`* · `team` · `workspace` · `notes` · `color` · `public` · `default_view`

### `asana_create_project_status` `W`

Post a status update to a project. status_type ∈ on_track|at_risk|off_track|on_hold|complete. text required (html_text optional).

Params: `project_gid`* · `status_type`* · `text` · `html_text` · `title` · `sanitize`

### `asana_create_section` `W`

Create a new section in a project. Optionally position via insert_before/insert_after (section GIDs).

Params: `project_gid`* · `name`* · `insert_before` · `insert_after`

### `asana_create_subtask` `W`

Create a subtask under a parent task.

Params: `parent_gid`* · `name`* · `assignee` · `notes` · `html_notes` · `due_on` · `start_on`

### `asana_create_task` `W`

Create a general task. Provide either projects[] (workspace inferred) or it lands in the workspace default. Supports assignee, notes/html_notes, dates, followers, tags, custom_fields (dates auto-wrapped).

Params: `name`* · `projects` · `workspace` · `assignee` · `notes` · `html_notes` · `due_on` · `start_on` · `followers` · `tags` · `custom_fields`

### `asana_duplicate_project` `W`

Duplicate an existing project (clone a board with its structure). include = fields to copy (array or comma string, e.g. ["members","task_notes","task_assignee"]). Returns an async job.

Params: `project_gid`* · `name`* · `team` · `include`

### `asana_duplicate_task` `W`

Duplicate a task (template instantiation). include = which fields to copy (array or comma string, e.g. ["notes","assignee","subtasks","dependencies"]). Returns an async job.

Params: `task_gid`* · `name`* · `include`

### `asana_instantiate_project_template` `W`

Create a new project from a project template (repeatable board setup). Returns an async job whose new_project holds the created project.

Params: `project_template_gid`* · `name`* · `team` · `public`

### `asana_instantiate_task_template` `W`

Create a new task from a task template (repeatable intake/ops task). Returns an async job whose new_task holds the created task.

Params: `task_template_gid`* · `name`*

### `asana_move_section` `W`

Move a task to a different section within its project. Fixes: no MCP tool for section moves.

Params: `task_gid`* · `section_gid`*

### `asana_remove_field_from_project` `W`

Detach a custom field from a project (removeCustomFieldSetting). Symmetric with asana_add_field_to_project.

Params: `project_gid`* · `custom_field_gid`*

### `asana_remove_follower` `W`

Remove follower(s) from a task.

Params: `task_gid`* · `followers`*

### `asana_remove_from_portfolio` `W`

Remove an item from a portfolio.

Params: `portfolio_gid`* · `item_gid`*

### `asana_remove_from_project` `W`

Remove a task from a project (un-add a board card). Symmetric with asana_add_to_project.

Params: `task_gid`* · `project_gid`*

### `asana_remove_tag` `W`

Remove a tag from a task.

Params: `task_gid`* · `tag_gid`*

### `asana_reorder_section` `W`

Reorder a section within its project (move a board column). Provide before_section or after_section (section GIDs).

Params: `project_gid`* · `section_gid`* · `before_section` · `after_section`

### `asana_set_custom_fields` `W`

Set custom fields on a task using correct type handling. Fixes: multi_enum arrays and date object wrappers that fail via official MCP.

Params: `task_gid`* · `custom_fields`*

### `asana_set_dates` `W`

Set start_on and/or due_on dates on a task. Fixes: start_on not exposed in official MCP schema, and due_on must be set first.

Params: `task_gid`* · `due_on` · `start_on`

### `asana_set_html_notes` `W`

Set rich-text notes on a task using html_notes. Fixes: "XML is invalid" error from official MCP.

Params: `task_gid`* · `html_notes`* · `sanitize`

### `asana_set_notes_safe` `W`

Set notes AND survive workspace automations that rewrite the task name / parse dates out of notes text (Rules and some integrations do this): write notes, wait settle_ms, then re-assert name + due_on. Use instead of raw notes edits on automated boards.

Params: `task_gid`* · `notes` · `html_notes` · `name` · `due_on` · `settle_ms`

### `asana_set_parent` `W`

Re-parent a task: make it a subtask of parent_gid, or detach to top level (parent_gid:null). Optional insert_before/insert_after sibling GIDs.

Params: `task_gid`* · `parent_gid` · `insert_before` · `insert_after`

### `asana_update_project` `W`

Update a project: name, notes, color, archived, public, default_view, dates.

Params: `project_gid`* · `name` · `notes` · `color` · `archived` · `public` · `default_view` · `due_on` · `start_on`

### `asana_update_section` `W`

Rename a section.

Params: `section_gid`* · `name`*


## Destructive (confirm-gated) (3)

### `asana_delete_project` `DESTRUCTIVE`

DESTRUCTIVE — permanently delete a project. Requires confirm:true (C13 gate). No-op + gate message otherwise.

Params: `project_gid`* · `confirm`

### `asana_delete_section` `DESTRUCTIVE`

DESTRUCTIVE — delete a section (Asana requires it be empty, or moves its tasks out). Requires confirm:true (C13 gate).

Params: `section_gid`* · `confirm`

### `asana_delete_task` `DESTRUCTIVE`

DESTRUCTIVE — permanently delete (trash) a task. Requires confirm:true (C13 gate). Without confirm it is a no-op that reports the gate.

Params: `task_gid`* · `confirm`