<!-- The markdown copy of https://oppalerts.com/docs/mcp/taxonomy_semantic_content_analyzer . All pages: https://oppalerts.com/docs/llms.txt -->

[Documentation](https://oppalerts.com/docs/) / [MCP](https://oppalerts.com/docs/mcp/) / taxonomy_semantic_content_analyzer

# taxonomy_semantic_content_analyzer

`POST https://mcp.oppalerts.com/mcp tool: taxonomy_semantic_content_analyzer`

How closely a piece of writing matches your target taxonomy categories, and the phrases that would bring it closer.

## What it does

You send a piece of writing and 1 to 3 target categories, at most one from each taxonomy. The tool returns the same data as the [Content Optimizer](https://oppalerts.com/docs/app/content/optimizer) page of the web app:

- For each target: its `similarity_score`, its rank in its taxonomy, and the 10 categories of that taxonomy that are nearest to the writing.
- For all targets together: the phrases of the targets that the writing does not use, most useful first, and the phrases that it already uses.

Get the category ids from [taxonomy_categories](https://oppalerts.com/docs/mcp/taxonomy_categories). A campaign keeps up to 3 targets as its taxonomy presets: [campaigns_settings](https://oppalerts.com/docs/mcp/campaigns_settings) returns them.

## Connect

```bash
claude mcp add --transport http oppalerts https://mcp.oppalerts.com/mcp
```

The first call opens a browser window for the OppAlerts login. [Connect an AI Agent](https://oppalerts.com/docs/mcp/) has the details.

## Parameters

**`text`string, required**

The writing to analyze, at most 8,192 bytes of UTF-8. A letter with an accent or a symbol counts as 2 or more bytes. A longer text is refused, not cut: send it in parts. An empty text, and a text of spaces only, are refused.

**`target_category_ids`list of whole numbers, required, 1 to 3 items, each 1 to 9007199254740991**

1 to 3 category ids, as taxonomy_categories answers them, at most one from each taxonomy. Two ids of one taxonomy are refused, and so is an id that is not a category. The answer holds one entry in taxonomies for each id, in the order sent.

## Strict Rules

- A field that is not in the list above is refused. The result then has `isError` true, and its text starts with `bad_param`. The error names the field: "<field> is not a field of this tool." The old name of a renamed field is refused in the same way.
- A bad value is refused, and the error names the field. A bad value is a value of the wrong type, a number with a fraction for a whole-number field, a value out of its range, or a value that is not in its list. A required field that you do not send is refused too. The tool never changes a value that you send.
- An error about the format of a call, such as a refused field, names the field. Its message ends with one sentence: "Read the documentation at https://oppalerts.com/docs for the correct format." Every other error has only its own sentence.

## The text and the targets

- The text can have at most 8,192 bytes. A letter with an accent or a symbol counts as 2 or more bytes. A longer text is refused, not cut: send it in parts.
- An empty text, and a text of spaces only, are refused.
- Send at most one target of each taxonomy. Two targets of one taxonomy are refused: a rank is a place in one taxonomy.
- An id that is not a category is refused. The same id two times is refused.
- The answer has one entry in `taxonomies` for each target, in the order that you sent them.

## Response

The answer has three fields:

**`taxonomies`list**

One entry for each target, in the order sent. Each entry has three fields:  `taxonomy`string The name of the taxonomy of the target. `target`object The target category: `category_id`, `category_label`, `similarity_score` (how near the writing is to the category; 100 is the nearest, and 0 or less is no likeness), `rank` (its place in its taxonomy, 1 is the nearest), and `rank_of` (the number of categories in the taxonomy). `nearest`list The 10 categories of the taxonomy that are nearest to the writing, nearest first. Each has `category_id`, `category_label`, `similarity_score`, and `rank`. When the target is not in this list, its `rank` tells its place.

**`phrases_to_add`list**

The phrases of the target categories that the writing does not use, most useful first. Each has `phrase` and `relevance_weight`, a weight of the phrase for its category. The weight sets the order. It is not a percent. A phrase that two targets have is in the list one time, with the higher weight. Use the phrases that belong in the writing. Do not try to use all of them.

**`phrases_in_text`list of strings**

The phrases of the target categories that the writing already uses.

## Example

### Call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "taxonomy_semantic_content_analyzer",
    "arguments": {
      "text": "Our boutique hotel in Sedona puts every guest near the red rock trails. Each of our guest rooms has a private patio, and breakfast is free when you book direct.",
      "target_category_ids": [
        4074921791751665,
        2358064203319202
      ]
    }
  }
}
```

### Response

A shortened answer. A real answer has 10 entries in each `nearest` list and every phrase of the targets.

```json
{
  "taxonomies": [
    {
      "taxonomy": "google-merchant",
      "target": {
        "category_id": 4074921791751665,
        "category_label": "Business & Industrial > Hotel & Hospitality",
        "similarity_score": 31.47,
        "rank": 1,
        "rank_of": 5595
      },
      "nearest": [
        {
          "category_id": 4074921791751665,
          "category_label": "Business & Industrial > Hotel & Hospitality",
          "similarity_score": 31.47,
          "rank": 1
        },
        {
          "category_id": 3254328027992189,
          "category_label": "Home & Garden > Decor > Bird & Wildlife Houses > Butterfly Houses",
          "similarity_score": 26.15,
          "rank": 2
        }
      ]
    },
    {
      "taxonomy": "iab-content-taxonomy",
      "target": {
        "category_id": 2358064203319202,
        "category_label": "Travel > Travel Type > Hotels and Motels",
        "similarity_score": 38.01,
        "rank": 2,
        "rank_of": 704
      },
      "nearest": [
        {
          "category_id": 3875482560662752,
          "category_label": "Travel > Travel Type > Bed & Breakfasts",
          "similarity_score": 44.9,
          "rank": 1
        },
        {
          "category_id": 2358064203319202,
          "category_label": "Travel > Travel Type > Hotels and Motels",
          "similarity_score": 38.01,
          "rank": 2
        }
      ]
    }
  ],
  "phrases_to_add": [
    {
      "phrase": "hotels and motels",
      "relevance_weight": 13.0
    },
    {
      "phrase": "hotel booking",
      "relevance_weight": 12.7734
    },
    {
      "phrase": "luxury hotels",
      "relevance_weight": 10.1023
    }
  ],
  "phrases_in_text": [
    "hotel",
    "boutique hotels",
    "boutique hotel",
    "hotels",
    "guest rooms",
    "guest room"
  ]
}
```

## Errors

An error returns as a tool result with `isError` true. Its text starts with the error code, except for `daily_limit`, whose text is only the sentence. The HTTP status shown for each code is its API status.

- `bad_param` (HTTP 400 in the API): a field is not a field of this tool, a required field is not sent, a value has the wrong type or is out of its range, the text is empty or has more than 8,192 bytes, two targets are of one taxonomy, the same id is sent two times, or an id is not a category. The error names the field.
- `backend_error` (HTTP 502 in the API): a server behind the tool did not answer. Try again in a few minutes.
- `daily_limit` (HTTP 429 in the API): the account has used all its calls for this tool today. [account_calls_left](https://oppalerts.com/docs/mcp/account_calls_left) shows when the count resets.

This tool has its own daily count. Calls through the API, MCP, and the web app use this count. It is not an index search, so it does not use the shared count of the `news_` and `prospects_` tools, and the error `one_at_a_time` does not apply to it.

## Same data in the API

```http
POST /v1/taxonomy/semantic_content_analyzer HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{"text": "Our boutique hotel in Sedona puts every guest near the red rock trails. Each of our guest rooms has a private patio, and breakfast is free when you book direct.", "target_category_ids": [4074921791751665, 2358064203319202]}
```

See [POST /v1/taxonomy/semantic_content_analyzer](https://oppalerts.com/docs/api/taxonomy_semantic_content_analyzer).

## Related pages

- [POST /v1/taxonomy/semantic_content_analyzer in the API](https://oppalerts.com/docs/api/taxonomy_semantic_content_analyzer)
- [taxonomy_categories: the category ids of a taxonomy](https://oppalerts.com/docs/mcp/taxonomy_categories)
- [taxonomy_taxonomies: the names of the taxonomies](https://oppalerts.com/docs/mcp/taxonomy_taxonomies)
- [The Content Optimizer page](https://oppalerts.com/docs/app/content/optimizer)
- [Use case: check draft topic relevance](https://oppalerts.com/docs/how-to/check-draft-topic-relevance)
- [Use case: compare content to target audiences](https://oppalerts.com/docs/how-to/compare-content-to-target-audiences)
