# add_sheet_conditional_format (https://sellersheetai.com/docs/mcp-api/tools/add_sheet_conditional_format)

> Add a conditional formatting rule to a range: a boolean rule (the default) that formats the cells meeting a condition, or a 2- or 3-stop colour gradient.

Access: **WRITE** · toolset google_workspace · family null

## Call it

MCP tool call:

```json
{
  "name": "add_sheet_conditional_format",
  "arguments": {
    "spreadsheet_id": "<spreadsheet_id>",
    "range_": "<range_>"
  }
}
```

Tool API (early access — contact us):

```bash
curl -X POST https://api.sellersheetai.com/api/v1/tools/add_sheet_conditional_format \
  -H "Authorization: Bearer $SELLERSHEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spreadsheet_id":"<spreadsheet_id>","range_":"<range_>"}'
```

## Arguments

| Name | Type | Required | Description |
|---|---|---|---|
| `spreadsheet_id` | string | yes | the spreadsheet ID (from its URL or get_sheet_metadata). |
| `range_` | string | yes | A1 range with sheet name (e.g. 'VOC!C4:C18'). |
| `rule_type` | string |  | the boolean condition; ignored when gradient is true. Allowed: NUMBER_GREATER (default), NUMBER_GREATER_THAN_EQ, NUMBER_LESS, NUMBER_LESS_THAN_EQ, NUMBER_EQ, NUMBER_NOT_EQ, NUMBER_BETWEEN, NUMBER_NOT_BETWEEN, TEXT_CONTAINS, TEXT_NOT_CONTAINS, TEXT_STARTS_WITH, TEXT_ENDS_WITH, TEXT_EQ, BLANK, NOT_BLANK, CUSTOM_FORMULA. |
| `values` | object[] |  | the condition's values — one for most types, two for NUMBER_BETWEEN / NUMBER_NOT_BETWEEN, one formula ('=…') for CUSTOM_FORMULA, none for BLANK / NOT_BLANK. |
| `background_color` | object[] |  | the format a boolean rule applies; colours are RGB floats 0–1. |
| `font_color` | object[] |  | the format a boolean rule applies; colours are RGB floats 0–1. |
| `bold` | boolean |  | the format a boolean rule applies; colours are RGB floats 0–1. |
| `gradient` | boolean |  | true for a colour-scale rule instead of a boolean one. |
| `min_color` | object[] |  | RGB floats 0–1. min_color and max_color are required when gradient is true; mid_color adds a third stop. |
| `mid_color` | object[] |  | RGB floats 0–1. min_color and max_color are required when gradient is true; mid_color adds a third stop. |
| `max_color` | object[] |  | RGB floats 0–1. min_color and max_color are required when gradient is true; mid_color adds a third stop. |
| `min_value` | string |  | where each stop sits — 'MIN', 'MAX', 'NUMBER:5', 'PERCENT:50', 'PERCENTILE:90' or a plain number. mid_value defaults to 'PERCENT:50' when mid_color is given. |
| `mid_value` | string |  | where each stop sits — 'MIN', 'MAX', 'NUMBER:5', 'PERCENT:50', 'PERCENTILE:90' or a plain number. mid_value defaults to 'PERCENT:50' when mid_color is given. |
| `max_value` | string |  | where each stop sits — 'MIN', 'MAX', 'NUMBER:5', 'PERCENT:50', 'PERCENTILE:90' or a plain number. mid_value defaults to 'PERCENT:50' when mid_color is given. |

## Result

- { sheetId: int, applied: true }

## Gotchas

- A boolean rule needs at least one of background_color, font_color or bold, or it is refused. The rule is inserted first (index 0), above every existing rule on the tab. Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused.

## Example

- # Green rows where rank ≤ 10 add_sheet_conditional_format( spreadsheet_id='1ABC...', range_='Competitors!A4:F18', rule_type='NUMBER_LESS_THAN_EQ', values=['10'], background_color=[0.85, 0.92, 0.83], bold=True, ) # Green (low) → yellow → red (high) on the gap_ratio column add_sheet_conditional_format( spreadsheet_id='1ABC...', range_='VOC!D4:D14', gradient=True, min_color=[0.57, 0.77, 0.49], mid_color=[1.0, 0.95, 0.6], max_color=[0.91, 0.26, 0.21], min_value='MIN', mid_value='NUMBER:5', max_value='MAX', )