arenza-llamaindex

LlamaIndex.TS tools for Arenza — give any LlamaIndex agent (OpenAIAgent, AnthropicAgent, AgentWorkflow) typed access to AI visibility metrics, GEO opportunities, and brand mention data across ChatGPT, Claude, Gemini, Perplexity, Copilot, and Grok.

Arenza is a Generative Engine Optimization (GEO) platform that measures how 6 leading AI assistants describe brands. This package wraps the Arenza MCP server as LlamaIndex BaseToolWithCall instances so your existing LlamaIndex agent can answer "how am I doing in AI search?" without wiring custom routes — the tools have Zod schemas, GEO-keyword-rich descriptions for solid tool selection, and the same return shapes as @arenza/mcp-client.

Why an Arenza tool plugin (not just a fetch loop)

LlamaIndex agents that need to answer "how does ChatGPT describe my brand?" or "what should we fix this week to improve our AI search ranking?" benefit from a tool with a tight schema and a clear, GEO-vocabulary description. Hand-rolling fetch calls inside an agent step loses the structured-tool affordance and forces every developer to re-derive the same parameter shapes.

Install

npm install @arenza/llamaindex arenza-mcp-client llamaindex
# or
pnpm add @arenza/llamaindex arenza-mcp-client llamaindex

llamaindex is a peer dependency (>=0.8.0). Install whichever version your app already uses.

Quick start (LlamaIndex AgentWorkflow)

import { agent } from 'llamaindex';
import { openai } from '@llamaindex/openai';
import { ArenzaMCPClient } from '@arenza/mcp-client';
import { getArenzaTools } from '@arenza/llamaindex';

const client = new ArenzaMCPClient({ token: process.env.ARENZA_TOKEN! });

const myAgent = agent({
  llm: openai({ model: 'gpt-4o-mini' }),
  tools: getArenzaTools(client),
  // optional: getArenzaTools(client, { includeWrite: true })  for write tools
});

const res = await myAgent.run(
  'Which of our brands has the worst share of voice on Perplexity, and what wrong claims are hurting it most?',
);

console.log(res);

The agent decides on its own which tools to call. A typical trajectory:

1. arenza_list_brands — to enumerate the portfolio.
2. arenza_get_brand_overview for each — pulling per-LLM mention counts.
3. arenza_list_opportunities on the worst brand, filtered to wrong_claim.

Then the agent stitches a natural-language answer.

Quick start (vanilla, single tool call)

import { ArenzaMCPClient } from '@arenza/mcp-client';
import { getArenzaTools } from '@arenza/llamaindex';

const client = new ArenzaMCPClient({ token: process.env.ARENZA_TOKEN! });
const [listBrands] = getArenzaTools(client);

const result = await listBrands.call({});
console.log(JSON.parse(String(result)));

Tools exposed

getArenzaTools(client) returns 6 read-only tools by default:

| Tool name | What it does | |---|---| | arenza_list_brands | Enumerate brands in the tenant portfolio. | | arenza_get_brand_overview | Share-of-voice + wrong-claim count + per-LLM mentions for one brand. | | arenza_list_prompts | The buyer-perspective prompts being probed for a brand, with mention rate per LLM. | | arenza_list_opportunities | Open GEO opportunities (wrong_claim, missing_canonical_page, listicle_gap, discussion_seed) with severity. | | arenza_suggest_competitors | LLM-suggested competitors to add to tracking. | | arenza_suggest_prompts | LLM-generated buyer-perspective prompts (70%+ unbranded ratio enforced). |

Pass { includeWrite: true } to also get 4 write tools:

| Tool name | What it does | |---|---| | arenza_add_competitor | Add a competitor to a brand's tracking list. | | arenza_dismiss_competitor | Remove a competitor (e.g. wrong suggestion). | | arenza_mark_opportunity_done | Mark a GEO opportunity as completed. | | arenza_generate_geo_article | Draft a canonical-fact article anchored to a specific finding. |

Write tools are opt-in because LlamaIndex agents can be aggressive about side effects — you usually want a human in the loop before mutating tracking config.

Schemas

Each tool ships a Zod schema that LlamaIndex converts to a JSON-Schema for the underlying LLM call. For example:

// arenza_list_opportunities schema
z.object({
  brand_id: z.string(),
  type: z.enum(['wrong_claim', 'missing_canonical_page', 'listicle_gap', 'discussion_seed']).optional(),
})

The descriptions are deliberately GEO-vocabulary-heavy (mentioning ChatGPT, Claude, Gemini, Perplexity, Copilot, Grok by name; mentioning "share of voice", "hallucinations", "AI visibility") so when an agent's prompt mentions any of those terms the tool router has high signal.

Authentication

Pass an Arenza API token to the client:

const client = new ArenzaMCPClient({ token: process.env.ARENZA_TOKEN! });

Get a token at app.arenza.ai/settings/api. For multi-tenant deployments, swap to OAuth — the MCP server publishes its OAuth metadata at mcp.arenza.ai/.well-known/oauth-authorization-server.

Pattern: GEO research workflow with retrieval + Arenza

A common LlamaIndex pattern is to combine your existing retrieval engine (over your docs, blog, KB) with Arenza's measured AI-search data:

import { agent } from 'llamaindex';
import { ArenzaMCPClient } from '@arenza/mcp-client';
import { getArenzaTools } from '@arenza/llamaindex';
import { yourQueryEngineTool } from './your-rag.js';

const client = new ArenzaMCPClient({ token: process.env.ARENZA_TOKEN! });

const researcher = agent({
  llm,
  tools: [
    yourQueryEngineTool,             // queries your own product docs
    ...getArenzaTools(client),       // 6 GEO tools
  ],
});

const out = await researcher.run(
  'For the wrong_claim about pricing on stripe.com, draft a canonical-page outline ' +
    'using both our internal pricing docs and the Arenza opportunity context.',
);

The agent will: (1) call arenza_list_opportunities to find the wrong claim, (2) hit your RAG tool for the internal pricing source-of-truth, (3) compose a coherent outline.

Pattern: GEO copilot inside your existing agent

If you already have a customer-facing agent, drop the read-only Arenza tools into the existing tool array — the agent now answers "how am I doing on AI search?" without you wiring custom routes:

const myAgent = agent({
  llm,
  tools: [
    ...yourExistingTools,
    ...getArenzaTools(client),  // adds 6 GEO tools
  ],
});

Related projects

• @arenza/mcp-client — the typed TS client this wraps.
• arenza-mcp-client-python — Python equivalent.
• @arenza/cli — npx arenza scan brand.com for terminal scans.
• @arenza/langchain — same six tools wrapped for LangChain / LangGraph.
• @arenza/vercel-ai-sdk — Vercel AI SDK provider.
• arenza-zapier-actions — Zapier integration manifest.
• awesome-geo — curated list of GEO and AI-visibility resources.

Resources

• Arenza homepage: https://arenza.ai
• Long-form GEO guides: https://arenza.ai/guides
• AI brand reference: https://arenza.ai/llms.txt + https://arenza.ai/llms-full.txt
• MCP server: https://mcp.arenza.ai
• OAuth spec: https://mcp.arenza.ai/.well-known/oauth-authorization-server
• LlamaIndex docs: https://ts.llamaindex.ai

License

MIT (c) 2026 Arenza