Mark

Refresh AI Search Volume

refresh_ai_volume

Re-estimates how often your buyer questions are asked in AI assistants. Fetches a fresh estimate from the provider for each active buyer question in every active market with a location and language; get_ai_visibility then shows each question's total across those markets and the per-market split. scope.summary states it as questions × markets. If this refuses because the workspace is not set up, call get_setup_status and check its rows, including skipped ones. Related: get_ai_visibility, save_strategy_item, set_up_market.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "refresh_ai_volume"
  }
}

Input Schema

Name	Required	Description	Default
No arguments

Output Schema

Name	Required	Description
`count`	No	Active questions estimated.
`scope`	No	What the run checks.
`state`	Yes
`markets`	No	Markets estimated in.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 3, 2026
- addedOutput schema / properties / count / description
```
Added value: +"Active questions estimated."
```
- addedOutput schema / properties / markets
```
Added value: +{
+  "description": "Markets estimated in.",
+  "type": "number"
+}
```

Changed1 schema field changedOct 14, 2026

addedOutput schema / properties / scope

Added value: +{
+  "additionalProperties": false,
+  "description": "What the run checks.",
+  "properties": {
+    "summary": {
+      "description": "The same line the app shows beside the button.",
+      "type": "string"
+    },
+    "units": {
+      "description": "How many checks, pages or questions.",
+      "type": "number"
+    }
+  },
+  "required": [
+    "units",
+    "summary"
+  ],
+  "type": "object"
+}

First observedOct 1, 2026

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, openWorldHint=true and idempotentHint=false, so the description does not need to re-state that this is a mutating external call. It adds real value beyond them: it explains that a live provider fetch happens per question per market, that only questions/markets meeting the location-and-language condition are covered, and that the call can refuse on an unconfigured workspace.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and its scope, then the failure path, then related tools, which is a sensible ordering. The 'scope.summary states it as questions x markets' clause is slightly inside-baseball and could be folded into the prior sentence. Otherwise there is little waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless tool with annotations and an output schema, the description covers what it does, what gets refreshed, where results surface (get_ai_visibility), and how to recover from the main failure mode. The one omission is the relationship to estimate_ai_volume, which is the sibling that most affects correct selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so there is no parameter meaning for the description to add; the schema-coverage signal is not meaningful here. The description instead explains downstream effects (scope.summary as questions x markets), which belongs to behavior rather than parameter semantics. Baseline for a parameterless tool is met.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Re-estimates how often your buyer questions are asked in AI assistants' plus 'fetches a fresh estimate from the provider'. The scope is pinned down (each active buyer question in every active market with a location and language). It does not distinguish itself from the sibling estimate_ai_volume, which is the one nearby tool an agent would likely confuse it with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear trigger (refresh stale AI volume estimates) and an explicit recovery path: if it refuses because the workspace is not set up, call get_setup_status and check rows including skipped ones. It also lists related tools. What is missing is any statement of when NOT to use it, particularly versus estimate_ai_volume.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Mark tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?