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

# bigdata_edit_watchlist

> Rename a watchlist, change its description, or add and remove companies and securities.

## Overview

The `bigdata_edit_watchlist` tool updates a watchlist you own in your Bigdata.com account. In a single call you can rename it, change or clear its description, add Knowledge Graph IDs, remove Knowledge Graph IDs, or any combination of these. Fields you leave out are unchanged.

## When to Use

Edit Watchlist is ideal for:

* **Rebalancing:** Adding new positions and removing closed ones after a portfolio update
* **Growing a list:** Extending a watchlist beyond the 100 items allowed at creation time
* **Housekeeping:** Renaming a watchlist or rewriting its description so it is easy to find later

<Tip>
  Items must be Knowledge Graph IDs, not company names or tickers. Resolve them with [`find_securities`](/mcp-reference/tools/find-securities) or [`get_securities`](/mcp-reference/tools/get-securities) first.
</Tip>

## How It Works

1. **Find** the watchlist `id` with [`bigdata_get_watchlist`](/mcp-reference/tools/bigdata-get-watchlist) if the user has not supplied it
2. **Resolve** any securities to add or remove to their Knowledge Graph IDs
3. **Call** `bigdata_edit_watchlist` with the `id` and at least one change
4. **Read** the returned watchlist to confirm the final `items`

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | ID of the watchlist to edit. |
| `name` | string | No | New display name. Cannot be an empty string. |
| `description` | string | No | New description. Pass an empty string to clear it. |
| `add_items` | string\[] | No | Knowledge Graph IDs to add. Merged into the current list. IDs already on the watchlist are ignored. Cannot be an empty array. |
| `remove_items` | string\[] | No | Knowledge Graph IDs to remove. IDs not on the watchlist are ignored. Cannot be an empty array. |

### Important Notes

* At least one of `name`, `description`, `add_items`, or `remove_items` is required. A call with only `id` returns the error `at least one of name, description, add_items, or remove_items is required`
* The same ID cannot appear in both `add_items` and `remove_items`
* Adds and removes are applied as set operations. There is no way to reorder items or replace the whole list in one call. To replace the list, remove the current items and add the new ones
* Only watchlists you own can be edited

## Data Returned

Returns a JSON object with a `watchlists` array containing the updated watchlist:

| Field | Description |
| - | - |
| `id` | Watchlist ID |
| `name` | Display name after the edit |
| `description` | Description after the edit, or `null` when cleared or never set |
| `items` | Full list of Knowledge Graph IDs on the watchlist after the edit |

```json theme={null}
{
  "watchlists": [
    {
      "id": "ea4c5039-6edb-45c1-9c51-37d3ab9689b0",
      "name": "US mega-cap tech and semis",
      "description": "Core large-cap technology holdings",
      "items": ["4A6F00", "D8442A"]
    }
  ]
}
```

## Usage Monitoring

The tool `bigdata_edit_watchlist` does not consume any quota.

## Practical Tips

### Confirm before removing

When a user asks to remove positions by name, resolve the names first and show the IDs and matching securities before calling the tool, so the wrong entity is not dropped.

### Next steps after editing

Pass the returned `items` to [`bigdata_portfolio_tearsheet`](/mcp-reference/tools/bigdata-portfolio-tearsheet) to refresh the grid for the updated list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.