> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.writesonic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Reference

> Every tool the Writesonic Agents MCP server exposes, what it does, and its REST equivalent.

The Agents MCP server exposes **20 tools**, plus two meta-tools for chaining calls. Every project-scoped tool takes a `project_id` argument, always call [`whoami`](#whoami) first to get it. Each tool maps to one endpoint in the [Agents REST API](/api-reference/agents/authentication); the REST path is listed with each tool (all paths are under `/api/v1/business`).

## Common arguments

| Argument                              | Type          | Description                                                                     |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------- |
| `project_id`                          | string (UUID) | **Required** for project-scoped tools. From `whoami`.                           |
| `view` / `action` / `report_type`     | string (enum) | Selects which slice a multi-purpose tool returns or which mutation it performs. |
| `filters` / `pagination` / `order_by` | object        | Narrow, page, and sort list results.                                            |

<Note>
  Most tools are **read-only**. The writes are `create_task`, `update_task`, and `comment_on_task`.
</Note>

***

## Identity & project

### whoami

Return the caller's identity, HQ teams, and the projects in the active workspace. **Call this first**: every project-scoped tool needs a `project_id`, and you get it here.
`GET /whoami`

### list\_project\_resources

List a project's reference resources by `resource`: `users`, `labels`, `settings`, `skills`, or `agents`. Pass the id `whoami` returned for you as `resource_id` to fetch your own project-scoped record (for example, your role in the project).
`POST /project-resources/query`

***

## Tasks

### query\_tasks

Query the project's tasks. `view="list"` returns a cursor page of task list items (with filter, sort, and pagination); `view="counts"` returns totals grouped by `group_by` (status, priority, assignee, or creator).
`POST /tasks/query`

### get\_task

Get one task with full detail, attachments and labels are always included. Pass `include` to also fetch the task's timeline, relations, and/or approvals.
`GET /tasks/{task_id}`

### create\_task

Create a task in the project. Purely additive: nothing is overwritten, and the task is visible and deletable in the product.
`POST /tasks`

### update\_task

Update a task: edit fields (`action="update_fields"`), transition its status (`action="transition_status"`), or (re)assign it (`action="assign"`). All changes are reversible.
`POST /tasks/update`

### comment\_on\_task

Create a comment on a task (`action="create"`). A reversible authoring action.
`POST /tasks/comments`

***

## Agent runs

### get\_agent\_runs

Get agent-run history for a task or an agent, or step-by-step progress for a single run. Scope `task_runs` needs `task_id`; `agent_runs` needs `agent_id`; `run_progress` needs `task_id` and `run_id`.
`POST /agent-runs/query`

***

## Playbooks

<Note>
  Playbooks are named `workflow` in the tool and endpoint identifiers below.
</Note>

### list\_workflows

List the project's playbooks or their status counts. Use `view="list"` for the paginated inventory (filter by type, status, or search) or `view="counts"` for totals.
`POST /workflows/query`

### get\_workflow

Get one playbook and its related data. `view` selects the slice: `detail`, `versions`, `version_detail` (needs `version_id`), `runs` (filter by run status or search), or `run_detail` (needs `workflow_run_id`).
`POST /workflows/get`

### list\_workflow\_components

List playbook building blocks. `view="components"` is the catalog, `view="batch"` fetches by `capability_ids`, and `view="hub_capabilities"` lists the workflows-hub capabilities.
`POST /workflows/components`

***

## Grids

### list\_grids

List a project's grids, or read one grid's detail or processing status, via the `view` enum (`detail` and `status` need `grid_id`). `view="column_options"` is the live catalog of column types you can add.
`POST /grids/query`

### get\_grid\_data

Read a grid's columns, rows, a single cell, a cell's run detail, or search rows via the `view` enum. A playbook column's `workflow_version_id` (from `view="columns"`) names its pinned version, pass it to `get_workflow` (`view="version_detail"`).
`POST /grids/data`

***

## Knowledge & brand

### search\_knowledge

Semantic search over the project's knowledge sources (RAG). Returns the matched chunks and, when `generate_answer` is true, a generated answer; set it false for raw chunks only. Optionally scope the search to specific sources.
`POST /knowledge/search`

### get\_knowledge\_source

List the project's knowledge sources, list its folders, or fetch one source's content. Does **not** cover the Brand Kit, that's a separate resource fetched with `get_brand_kit`.
`POST /knowledge/sources`

### get\_brand\_kit

Get the project's brand kit. `view="catalog"` lists the available brand-kit section names only; use it to answer "what sections does my brand kit have." Other views compose the full section content.
`POST /brand-kit`

***

## Content intelligence

### get\_ci\_dashboard

Project-level content-intelligence reads: page summary, live summary, available filters, countries, the ranked page list, page groups, and the page-list column scope, selected by `view`. `view="pages"` is also how you resolve a page name or URL to a `page_id`.
`POST /content-intelligence/dashboard`

### get\_page\_report

Per-page content-intelligence report selected by `report_type` (SEO, AI citations, funnels, traffic, SERP, keywords, lifecycle, activity). Some reports require `market_id`. Resolve `page_id` from `get_ci_dashboard` (`view="pages"`).
`POST /content-intelligence/page-report`

***

## Integrations & attachments

### list\_integrations

List the workspace's connected apps and integration connections. `view="apps"` returns the app catalog; `view="apps_overview"` groups connections by app with active/inactive counts; `view="connections"` lists individual connections.
`POST /integrations/query`

### download\_attachment

Get a short-lived presigned download URL for a task or comment attachment. Returns the URL plus filename and content type, not the file bytes. For a task attachment, pass `task_id`.
`POST /attachments/download-url`

***

## Meta-tools (MCP only)

These two tools have no REST equivalent, they orchestrate the tools above in a single request.

### execute\_batch

Run up to 10 linear tool calls in one request, passing results between steps. Use it for chains with no loops or conditionals.

### execute\_plan

Run server-side TypeScript ("code mode") for plans that need loops, conditionals, or three-plus calls with intermediate data shaping. Never use it to skip resolving which project you mean.

<Card title="Full request & response schemas" icon="code" href="/api-reference/agents/authentication">
  The [Agents REST API reference](/api-reference/agents/authentication) documents the exact request body and response shape for each tool's endpoint.
</Card>