Documentation / MCP / taxonomy_semantic_content_analyzer

taxonomy_semantic_content_analyzer

POSThttps://mcp.oppalerts.com/mcptool: 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 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. A campaign keeps up to 3 targets as its taxonomy presets: campaigns_settings returns them.

Connect

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 has the details.

Parameters

textstring, 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_idslist 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:

taxonomieslist
One entry for each target, in the order sent. Each entry has three fields:
taxonomystring
The name of the taxonomy of the target.
targetobject
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).
nearestlist
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_addlist
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_textlist of strings
The phrases of the target categories that the writing already uses.

Example

Call

{
  "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.

{
  "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 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

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.