Skip to main content
Glama

serpmantics

by io.github.AmauryDvl
OverviewDiscussionsAdmin

create_guides

create_guides

Create new guides

Create one or more new guides based on provided queries. Each guide targets exactly ONE engine and ONE analysis mode, chosen with the optional source field (default google).

How to request each guide type:

  1. Google SERP guide (1 credit per guide): omit source, or pass source: "google". Example payload: {"queries": ["best crm"], "lang": "en-us"} 1bis. Google AI Overview guide (1 credit per guide). Two modes, like AI engines: source: "google_ai_overview" builds the guide from the TEXT of Google's AI answers (AI Overview, completed with AI Mode answers) ; source: "google_ai_overview_citations" builds it from the content of the web SOURCES those answers cite (recommended for GEO). Same language/country parameters as a Google SERP guide, 1 credit per guide in both modes. Example payload: {"queries": ["best crm"], "lang": "en-us", "source": "google_ai_overview_citations"}

  2. LLM ANSWER guide (4 credits per guide): pass the engine name alone, e.g. source: "chatgpt". The guide is built from the answer text the AI generates for the query. Example payload: {"queries": ["best crm"], "lang": "en-us", "source": "chatgpt"}

  3. LLM CITATIONS guide (4 credits per guide) [RECOMMENDED AI mode]: pass the engine name with the _citations suffix, e.g. source: "chatgpt_citations". The guide is built from the content of the web pages the AI cites in its answer. Example payload: {"queries": ["best crm"], "lang": "en-us", "source": "chatgpt_citations"}

Which AI mode to pick? For GEO (getting a page visible in AI answers), prefer <engine>_citations: AI engines send traffic by CITING pages as sources, so the winning move is to look like the pages they cite. The answer-text mode (<engine> alone) is mostly useful to analyze how the AI phrases its own answer. When in doubt, pick <engine>_citations.

The same two modes exist for every AI engine (chatgpt, perplexity, claude, gemini, grok, mistral, deepseek). To optimize the same page for several engines or modes (e.g. Google AND ChatGPT answers AND ChatGPT sources), create one guide per source value on the same query.

IMPORTANT, HOW TO READ THE RESPONSE OF THIS ENDPOINT, WHICH SPENDS CREDITS. Queries listed in guidesFailed are PROVEN not to have produced a guide and their credit was given back (unless the account has unlimited credits, where nothing was reserved): re-sending them is free and correct. Queries listed in guidesUnknown have an UNDECIDABLE outcome and their credit is deliberately KEPT, because the guide was most likely written: DO NOT re-send them, you would pay for the same guide twice. Look them up in GET /api/v1/guides after a few minutes instead, and contact support if nothing shows up. Finally, a 200 is NOT a promise that every query produced a guide: compare guides.length with the number of queries you sent, never read success alone, and never re-send a query just because it is missing from guides.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
langYesLanguage code for the guides
sourceNoTarget engine AND analysis mode the guide optimizes for. One guide = one source. `google` analyzes the Google SERP (1 credit per guide). Google's AI answers have the same two modes as AI engines : `google_ai_overview` analyzes the TEXT of the AI answers (AI Overview, completed with AI Mode) ; `google_ai_overview_citations` analyzes the content of the web SOURCES those answers cite, the recommended mode for GEO. 1 credit per guide in both modes, same language/country parameters as `google`. For AI engines (chatgpt, perplexity, claude, gemini, grok, mistral, deepseek), pick the mode: `<engine>` analyzes the AI's generated ANSWER for the query; `<engine>_citations` analyzes the content of the web SOURCES the AI cites, which is the recommended mode for GEO (become one of the cited sources). Both AI modes cost 4 credits per guide. Omit for the default `google`.
queriesYesArray of queries to create guides for

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / source / description
      Previous value: -"Target engine AND analysis mode the guide optimizes for. One guide = one source. `google` analyzes the Google SERP (1 credit per guide). Google's AI answers have the same two modes as AI engines : `google_ai_overview` analyzes the TEXT of the AI answers (AI Overview, completed with AI Mode) ; `google_ai_overview_citations` analyzes the content of the web SOURCES those answers cite, the recommended mode for GEO. 1 credit per guide in both modes, same language/country parameters as `google` (both modes are in beta and currently restricted to administrators). For AI engines (chatgpt, perplexity, claude, gemini, grok, mistral, deepseek), pick the mode: `<engine>` analyzes the AI's generated ANSWER for the query; `<engine>_citations` analyzes the content of the web SOURCES the AI cites, which is the recommended mode for GEO (become one of the cited sources). Both AI modes cost 4 credits per guide. Omit for the default `google`."New value: +"Target engine AND analysis mode the guide optimizes for. One guide = one source. `google` analyzes the Google SERP (1 credit per guide). Google's AI answers have the same two modes as AI engines : `google_ai_overview` analyzes the TEXT of the AI answers (AI Overview, completed with AI Mode) ; `google_ai_overview_citations` analyzes the content of the web SOURCES those answers cite, the recommended mode for GEO. 1 credit per guide in both modes, same language/country parameters as `google`. For AI engines (chatgpt, perplexity, claude, gemini, grok, mistral, deepseek), pick the mode: `<engine>` analyzes the AI's generated ANSWER for the query; `<engine>_citations` analyzes the content of the web SOURCES the AI cites, which is the recommended mode for GEO (become one of the cited sources). Both AI modes cost 4 credits per guide. Omit for the default `google`."
  2. Changed2 schema fields changed
    • changedInput schema / properties / source / description
      Previous value: -"Target engine AND analysis mode the guide optimizes for. One guide = one source. `google` analyzes the Google SERP (1 credit per guide). For AI engines (chatgpt, perplexity, claude, gemini, grok, mistral, deepseek), pick the mode: `<engine>` analyzes the AI's generated ANSWER for the query; `<engine>_citations` analyzes the content of the web SOURCES the AI cites, which is the recommended mode for GEO (become one of the cited sources). Both AI modes cost 4 credits per guide. Omit for the default `google`."New value: +"Target engine AND analysis mode the guide optimizes for. One guide = one source. `google` analyzes the Google SERP (1 credit per guide). Google's AI answers have the same two modes as AI engines : `google_ai_overview` analyzes the TEXT of the AI answers (AI Overview, completed with AI Mode) ; `google_ai_overview_citations` analyzes the content of the web SOURCES those answers cite, the recommended mode for GEO. 1 credit per guide in both modes, same language/country parameters as `google` (both modes are in beta and currently restricted to administrators). For AI engines (chatgpt, perplexity, claude, gemini, grok, mistral, deepseek), pick the mode: `<engine>` analyzes the AI's generated ANSWER for the query; `<engine>_citations` analyzes the content of the web SOURCES the AI cites, which is the recommended mode for GEO (become one of the cited sources). Both AI modes cost 4 credits per guide. Omit for the default `google`."
    • changedInput schema / properties / source / enum
      Previous value: -[
-  "google",
-  "chatgpt",
-  "chatgpt_citations",
-  "perplexity",
-  "perplexity_citations",
-  "claude",
-  "claude_citations",
-  "gemini",
-  "gemini_citations",
-  "grok",
-  "grok_citations",
-  "mistral",
-  "mistral_citations",
-  "deepseek",
-  "deepseek_citations"
-]New value: +[
+  "google",
+  "google_ai_overview",
+  "google_ai_overview_citations",
+  "chatgpt",
+  "chatgpt_citations",
+  "perplexity",
+  "perplexity_citations",
+  "claude",
+  "claude_citations",
+  "gemini",
+  "gemini_citations",
+  "grok",
+  "grok_citations",
+  "mistral",
+  "mistral_citations",
+  "deepseek",
+  "deepseek_citations"
+]
  3. First observed

TDQS

A4.9/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It goes beyond typical by explaining credit spending (1 vs 4 credits), the meaning of guidesFailed vs guidesUnknown, the fact that a 200 response does not guarantee guide creation, and the specific rule that credits for unknown outcomes are deliberately kept and must not be re-requested. This is exceptional transparency about side effects and response interpretation.

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?

The description is long but well-structured with numbered sections and a clear hierarchy: purpose, how-to by guide type, mode selection advice, and critical response-reading rules. It is not maximally concise, and some content (e.g., the source mode explanations) is partially repeated from the schema, but every substantial section earns its place given the endpoint's credit-spending nature and ambiguous response semantics.

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

Completeness5/5

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

Despite having no output schema, the description explains exactly how to interpret the response: compare guides.length with the number of queries, do not trust success alone, handle guidesFailed vs guidesUnknown correctly, and follow up via GET /api/v1/guides for unknown outcomes. It also covers all parameters, default behavior, credit implications, and multi-engine usage. An agent has everything needed to call this endpoint safely and correctly.

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

Parameters5/5

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: credit costs per source, the GEO-oriented distinction between answer-text and citations modes, concrete example payloads, and a decision heuristic for choosing modes. It also explains the default value of source and the semantic range of the enum, making this far more useful than the schema alone.

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

Purpose5/5

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

The description opens with a specific verb and resource: 'Create one or more new guides based on provided queries.' It also clarifies the unique scope of a guide (exactly ONE engine and ONE analysis mode), which distinguishes it from the many other create_* siblings that operate on different resource types (eeat, intent, meta, outline, etc.). An agent can immediately tell what this tool does and how it differs from sibling tools.

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

Usage Guidelines5/5

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

The description provides detailed, explicit instructions for when to use each guide type, including exact source values, examples, credit costs, and a clear recommendation: 'When in doubt, pick <engine>_citations.' It also explains when to create multiple guides and, in the IMPORTANT section, exactly when it is safe to re-send queries versus when it is not. This is exemplary usage guidance.

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

All serpmantics toolsInspect
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