SEO data for AI agents and LLM apps: give your AI real numbers

Why do LLMs get SEO metrics wrong?

Language models get SEO metrics wrong because the numbers are not in the model: authority scores, backlink counts and search volumes live in vendors' databases, change every month, and differ between vendors, so a model asked for one fills the gap with a plausible guess. The guess often looks right, which is the problem.

Three things make SEO numbers especially hard for a model on its own:

• They are proprietary scales. "Domain authority" means Moz DA, Ahrefs DR, Semrush Authority Score or MrKeyword Link Authority, each a different model over a different index (see What is domain authority?). A model cannot compute any of them.
• They move. Links are gained and lost, volumes shift with seasons, and anything a model saw in training is out of date by the time someone asks.
• Most domains and keywords were never written about. For a small business site or a long-tail keyword, there is nothing to remember, so any figure is invented.

The fix is not a better prompt. It is giving the model a way to fetch the figure from a source, with the source's date and label attached, and telling it to quote only what the tool returned.

How does tool calling give an AI agent real SEO data?

Tool calling lets the model ask your application to run a function: you declare the function with a JSON Schema, the model replies with a structured call instead of an answer, your server runs it, and you send the result back so the model can answer from it. Anthropic and OpenAI document the same loop with different field names.

1. Declare the tools

   Send the tool definitions with the request. Anthropic's Define tools page lists name, description and input_schema; OpenAI's function calling guide uses type: "function", name, description, parameters and strict.

2. The model returns a call

   Claude stops with stop_reason: "tool_use" and a tool_use block naming the tool and its input. An OpenAI model returns a function_call item with a call_id, the name and JSON-encoded arguments. Either may ask for several calls at once.

3. Your server runs it

   Your code calls the SEO API with your key. The model never sees the key and never makes the HTTP request itself.

4. Send the result back

   Return it as a tool_result block with the matching tool_use_id (Claude) or a function_call_output item with the matching call_id (OpenAI). The model then answers, or asks for another call.

Anthropic's tool use overview notes that with the default auto setting, Claude calls a tool when the request maps to the tool's described capability and the answer is not already in context. That is exactly the behaviour you want for metrics: the description is what tells the model "numbers come from here".

What does an SEO tool definition look like?

An SEO tool definition is a name, a description that says what the tool returns and when to use it, and a JSON Schema for its inputs; the same schema works for Claude, OpenAI models and most other function-calling models. Here are two tools over MrKeyword's Data API, one for a domain and one for a list of keywords.

[
  {
    "name": "seo_domain_overview",
    "description": "Returns SEO data for one domain from MrKeyword's own index: link authority (0-100), estimated monthly organic clicks with a low-high range, referring domains, backlinks and top anchors, indexed pages, registration date and hosting. Use it whenever the user asks about a website's authority, backlinks or traffic. Every figure has a label (Measured, Derived, Estimated, Predicted or Not available), an asOf date and a source: repeat the label and date in your answer. If a value is null, say it is not available and give the reason; never estimate it yourself. It does not return live Google rankings.",
    "input_schema": {
      "type": "object",
      "properties": {
        "domain": { "type": "string", "description": "A bare domain such as example.com, without https:// or a path." }
      },
      "required": ["domain"],
      "additionalProperties": false
    }
  },
  {
    "name": "seo_keyword_metrics",
    "description": "Returns monthly search volume (Google Ads Keyword Planner, looked up live when not yet stored), CPC range, competition, difficulty (0-100, estimated) and search intent for up to 100 keywords in one market. Use it whenever the user asks how many people search for something or how hard a keyword is. Send all keywords in one call rather than one call per keyword. Keywords not in MrKeyword's database come back with found: false; say so rather than guessing a volume.",
    "input_schema": {
      "type": "object",
      "properties": {
        "keywords": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "The keywords, lower case." },
        "market": { "type": "string", "enum": ["US", "CA", "IN", "GB", "AU"], "description": "Country market for volume and difficulty." }
      },
      "required": ["keywords", "market"],
      "additionalProperties": false
    }
  }
]

The descriptions do most of the work. Anthropic's guidance calls detailed descriptions "by far the most important factor in tool performance" and suggests saying what the tool does, when to use it and what it does not return. OpenAI's guide makes the same point and recommends enums to rule out invalid inputs, which is why market is an enum. Both also advise keeping the tool count small: two or three well-described SEO tools beat a tool per endpoint.

How does the server run the tool call?

Your server maps each tool name to one fixed API request, adds the key from an environment variable, and returns the JSON (or an error the model can read). Here is a minimal handler in JavaScript using MrKeyword's base URL https://app.mrkeyword.io/api/v1.

const BASE = "https://app.mrkeyword.io/api/v1";
const headers = {
  "Authorization": "Bearer " + process.env.MRKEYWORD_API_KEY, // mkd_... kept on the server
  "content-type": "application/json",
};

async function runSeoTool(name, input) {
  let res;
  if (name === "seo_domain_overview") {
    res = await fetch(BASE + "/domains/overview?domain=" + encodeURIComponent(input.domain), { headers });
  } else if (name === "seo_keyword_metrics") {
    res = await fetch(BASE + "/keywords/metrics", {
      method: "POST", headers,
      body: JSON.stringify({ keywords: input.keywords, market: input.market }),
    });
  } else {
    return { error: "Unknown tool" };
  }
  const body = await res.json();
  if (!res.ok) return { error: body.error, status: res.status }; // 402 credits, 429 rate limit
  return body.data; // keep meta (credits) for your own logs, not for the model
}

Every successful response is { data, meta }. Give the model data, and keep meta.creditsCharged and meta.creditsRemaining for your own usage tracking. Anthropic recommends tool responses that return only high-signal information, so consider trimming each figure to its value, label, asOf and source before sending it back. Long backlink lists waste context; summarise or cap them.

Add one line to your system prompt as well, in your own words: SEO figures must come from the tools, with their label and date, and anything the tools do not return is "not available". This is our practice rather than a vendor rule, but it stops the model from padding an answer with remembered numbers.

Which SEO endpoints should an AI agent use?

Map each kind of user question to one endpoint, and prefer the cheapest endpoint that answers it. These are the MrKeyword endpoints an assistant usually needs, with their price per call.

How do you save credits with batching and caching?

Batch every list into one call, because MrKeyword charges difficulty, intent and clustering at 1 credit per 10 keywords, and cache results by domain or keyword so repeat questions cost nothing. Agents are chatty: without both, the same lookup is often paid for several times in one conversation.

• Batch. 100 keywords' difficulty is 10 credits in one POST, but 100 credits as 100 single calls (each call is charged at least 1). Tell the model in the tool description to send all keywords at once, and accept arrays in the schema.
• Cache. Key a cache on endpoint plus input, and reuse the result within a conversation and across users. The data is computed from MrKeyword's index and carries an asOf date, so a cache of a few hours to a day for authority and traffic keeps answers current enough for most assistants.
• Pick the cheap endpoint. If the user only asked about authority, /domains/authority at 1 credit beats /domains/overview at 3.
• Watch the balance. GET /api/v1/usage costs 0 credits. A 402 means the balance is spent; a 429 carries Retry-After; a 500 is not charged.

Worked example: an assistant that handles 1,000 conversations a month, each running one domain overview (3 credits) and metrics for 10 keywords (10 credits), uses 13,000 credits. That fits API Starter at $29 a month (20,000 credits). The free Developer plan's 500 credits a month covers building and testing. API Growth is $99 for 100,000 credits, API Scale $299 for 400,000, and a $20 pack adds 10,000 credits that last 12 months. For a breakdown of tool-builder costs, see SEO API: how to build your own keyword or domain tool.

How do you keep SEO API keys safe in an AI app?

Keep the key in a server environment variable and make every API call from your backend; never put it in a prompt, a tool result, client-side code or anything the model can repeat. A model can be talked into printing its context, so anything in the context should be safe to leak.

• Server only. MrKeyword's API allows cross-origin requests, but its documentation says keys belong on a server, not in a browser.
• Fixed endpoints. Let the model choose a tool and its inputs, never a URL. Text the model reads from a web page or a user could otherwise steer requests.
• One key per environment. Workspace owners and admins can create up to 20 live keys, each with an optional expiry, and revoke one on the Data API screen; it stops working on the next call.
• Per-user limits. Your app pays for every call, so cap tool calls per user and per conversation in your own code.

Data API or MCP server: which one do you need?

Use the Data API when you are building your own app for many users on MrKeyword's index; use the MCP server when a person wants their own MrKeyword workspace, with its Search Console, ranking and audit data, inside an AI assistant such as Claude or Cursor. They use different keys and answer different questions.

The Model Context Protocol is an open standard for connecting AI applications to external systems, so an MCP-capable client discovers MrKeyword's tools itself and you write no handler. For setup, see connecting Claude to an SEO MCP server. If the question is instead whether AI assistants mention your brand, that is a different job, covered by AI visibility tracking.

What MrKeyword does not do

MrKeyword's Data API gives an agent MrKeyword's own, labelled data; it does not give it live Google results, a complete web backlink index, or volume for every keyword. Tell your model these limits in the tool descriptions so it can tell users.

• No live SERPs. Nothing is scraped from Google. /serp/predicted and /domains/organic-keywords are labelled Predicted from MrKeyword's public page index.
• Own index coverage. Backlinks and referring domains are those MrKeyword's crawler and the Common Crawl web graph have found, so counts are lower than the largest commercial indexes.
• Estimates are labelled. Traffic and difficulty are Estimated; a domain MrKeyword has not seen returns nulls with a reason.
• Five markets, with a daily live-lookup allowance. Volumes are Google Ads Keyword Planner figures for US, CA, IN, GB and AU. A keyword MrKeyword has not stored is looked up live and saved, up to the API plan's daily allowance of live lookups; a keyword with no volume answers found: false and is not charged.
• No model included. MrKeyword sells the data, not the language model; you bring Claude, an OpenAI model or another.

Questions and answers