LightSpot MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@LightSpot MCP Serveraudit example.com and tell me why ChatGPT doesn't cite it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@lightspot/mcp
MCP server for LightSpot.ai — run SEO & GEO audits, read their results and our experts' reports, and import editorial calendars from any MCP client (Claude Desktop, Claude Code, Cursor, …).
It wraps the LightSpot public API (/v1) as MCP tools, so an AI assistant can "audit this site and tell me why ChatGPT doesn't cite it" in one step.
Requirements
A LightSpot API key (
lspai_live_…) — create one in LightSpot → Integrations → API keys. API access is included in the Zenith plan.Node.js ≥ 18 (run on demand via
npx, nothing to install globally).
Related MCP server: sightvane-mcp
Setup
Add the server to your MCP client config and set your API key:
{
"mcpServers": {
"lightspot": {
"command": "npx",
"args": ["-y", "@lightspot/mcp"],
"env": {
"LIGHTSPOT_API_KEY": "lspai_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}Claude Desktop →
claude_desktop_config.jsonClaude Code →
claude mcp addor your project's.mcp.jsonCursor →
~/.cursor/mcp.json
Environment variables
Variable | Required | Description |
| yes | Your API key ( |
| no | Override the API base URL (defaults to |
Tools
Tool | What it does |
| Run an audit on a URL, wait for it to finish, and return a summary (score, top actions, main issues). The one-shot "audit this and tell me what's wrong." |
| Start an audit without waiting (returns the audit id). |
| Lightweight status of an audit ( |
| Audit results — a trimmed summary by default, or the full payload with |
| List the sites on your account (with their latest score). |
| A site's metadata and recent audits. |
| A site's paginated audit history. |
| Get a site's latest competitor analysis (detected competitors, tiers, citations, recommendations). Read-only — does not trigger a new analysis. |
| Read the latest report from our 8 experts (technical SEO, content, GEO, structured data, sitemaps, performance, visual, brand authority) for a site or a given audit: prioritized findings, recommended actions with steps, limitations and ready-to-apply artifacts. Summary by default, |
| Read a site's calendar over an ISO date range, including imported slots and content already preparing, scheduled, or published. |
| Import or update up to 50 dated editorial slots. Idempotent with |
Example prompts
"Audit https://example.com and give me the top 3 things to fix for AI visibility."
"List my LightSpot sites and which one has the lowest score."
"Get the full results for audit
<id>and group the issues by severity.""What competitors were detected for my site
<siteId>, and what should I do about them?""Read the experts' report for my site
<siteId>and fix what the structured-data expert recommends in my codebase.""Create a four-week editorial calendar for my site
<siteId>with two LinkedIn posts and one educational Reddit post per week, then import it into LightSpot.""Show me everything planned or published for site
<siteId>between 2026-08-01T00:00:00+02:00 and 2026-09-01T00:00:00+02:00."
Notes
Quotas (audits/month, pages/audit) and per-key rate limits follow your LightSpot plan.
Importing editorial slots does not consume AI credits and never generates, schedules, or publishes content automatically.
The full REST API reference lives at lightspot.ai/docs/api.
License
MIT
Available Tools
11 toolsaudit_and_waitAudit a URL and wait for the resultA
Lance un audit SEO & GEO LightSpot sur une URL, attend la fin, et renvoie un résumé (score, top actions, principaux problèmes). Idéal pour « audite ce site et dis-moi quoi corriger ». Peut prendre 1 à 3 minutes ; au-delà du délai, renvoie l'id pour suivre via get_audit_status / get_audit.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL à auditer (page d'accueil ou page précise). | |
| maxPages | No | Nombre de pages à crawler (plafonné par votre plan). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the 1–3 minute blocking duration, the timeout behavior (returns the id for polling), and what the result contains. It does not mention plan/quota consumption or whether a re-run duplicates an audit, which are the remaining behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences: what it does, when to reach for it, and the latency/timeout escape hatch. Front-loaded with the action, no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must describe return values — and it does (score, top actions, top issues, or an id on timeout). Combined with the latency warning and the polling alternatives, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both url and maxPages are already documented in the schema including the plan cap. The description adds no parameter-level syntax or format detail beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (lance un audit SEO & GEO LightSpot sur une URL), plus the synchronous behavior (attend la fin) and the returned payload (score, top actions, principaux problèmes). It names the downstream tools (get_audit_status / get_audit) so an agent can separate it from run_audit and the status/retrieval siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete usage scenario (« audite ce site et dis-moi quoi corriger ») and an explicit fallback path when the wait times out. It does not explicitly contrast with run_audit (the presumably fire-and-forget sibling), so the when-not-this-tool case is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_editorial_calendarCreate or update an editorial calendarA
Importe jusqu'à 50 créneaux éditoriaux datés dans le calendrier d'un site LightSpot. L'import est idempotent : externalId permet de mettre un créneau à jour sans doublon. Cette action crée uniquement le planning ; elle ne génère, ne planifie et ne publie aucun contenu et ne consomme aucun crédit IA.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Créneaux à afficher dans le calendrier LightSpot. | |
| siteId | Yes | Identifiant du site LightSpot. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the 50-item cap, idempotent upsert semantics via externalId, and the absence of AI-credit consumption or content side effects. It stops short of stating whether slots absent from the batch are preserved or removed (merge vs replace) and says nothing about required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: capability and limit first, then the idempotency mechanism, then the negative scope. No filler, and the most decision-relevant facts (limit, idempotency, no side effects) are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter write tool with no annotations and no output schema, the description covers limits, idempotency, and side-effect boundaries well. The remaining gap is the merge/replace semantics of a re-import and any permission requirements, which an agent would want before mutating a calendar.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: externalId is framed as the idempotency key that updates a slot instead of duplicating it, and items is characterized as 'créneaux datés'. This goes beyond the schema's field-level descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (import/upsert up to 50 dated editorial slots) and the exact resource (a LightSpot site's editorial calendar), which cleanly separates it from the read-only sibling get_editorial_calendar. The boundary statement ('creates only the planning') prevents confusion with content-generation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for use and strong negative scoping — it does not generate, schedule, or publish content and burns no AI credits, so an agent knows this is a pure planning call. It never names an explicit alternative tool, but no sibling competes for this write path, so the omission is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_auditGet audit resultsA
Récupère les résultats d'un audit : résumé par défaut (score, top actions, principaux problèmes), ou payload complet avec full=true (toutes les pages et tous les problèmes).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Identifiant de l'audit. | |
| full | No | true pour le payload complet, sinon un résumé. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the shape of the return data (score, top actions, main issues vs. all pages and problems). It omits any statement about permissions, error conditions, or whether the audit must be completed before retrieval.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads the default behavior before the full=true override. Every clause earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description sensibly describes what each mode returns, which is the key missing structured information. The only gap is the absence of any note about the audit needing to exist/be complete, which the sibling get_audit_status implies is a real concern.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema. The description largely restates that full=true yields the complete payload and default yields a summary, adding the concrete contents of each mode but no format or sizing details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Récupère) and resource (résultats d'un audit) and outlines the two response modes. It never names or contrasts with the closely related siblings get_audit_status or list_site_audits, so an agent must reason about the distinction itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly tells the agent which mode to pick: default summary versus full=true for the complete payload, and enumerates what each contains. It does not address prerequisites (e.g. whether the audit must be finished) or point to the sibling tools that surface audit status/listings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_audit_statusGet audit statusA
Statut léger d'un audit (PENDING/RUNNING/DONE/FAILED) avec une progression de 0 à 1.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Identifiant de l'audit. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the return state space and 0-1 progression range that the schema does not. It stops short of stating read-only semantics, permissions, or polling/rate behavior for what is clearly a status-polling tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the state list and range are packed efficiently. Slightly terse given the tool's role, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the description usefully covers the returned status values and progression range. Remaining gaps (when to poll vs. wait, auth) are minor for a simple status check.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% on the single 'id' parameter, so the schema already documents it fully. The description adds nothing about the id format or origin, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('statut léger d'un audit') and enumerates the possible states and progression range. The word 'léger' hints at a lightweight alternative to get_audit, but no sibling is explicitly named, so differentiation is only implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the PENDING/RUNNING/DONE/FAILED enum suggests polling, and 'léger' hints this is the cheap status check versus get_audit or audit_and_wait. However, no explicit when-to-use, when-not-to-use, or named alternative is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_competitorsGet a site's competitor analysisA
Récupère la dernière analyse concurrentielle existante d'un site (concurrents détectés, tiers, citations, recommandations). Ne déclenche PAS de nouvelle analyse — si aucune n'a encore été lancée depuis l'app, renvoie status: "NONE".
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes | Identifiant du site. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it declares read-only behavior (no new analysis triggered) and discloses the edge-case return value status:'NONE' when nothing exists. It omits auth/rate-limit context but covers the key behavioral traits an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the primary purpose with returned fields first, then the critical constraint and edge case. No filler; every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations, yet the description enumerates the returned fields and the 'NONE' status, which is enough for correct invocation and expectation-setting. Minor gaps remain around what 'latest' means (freshness) but overall it is fit for purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (siteId is fully documented), so the schema already handles parameter meaning. The description adds nothing about siteId format or constraints, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (récupère/récupère la dernière analyse) and resource (analyse concurrentielle d'un site), and enumerates the returned content (concurrents détectés, tiers, citations, recommandations). An agent immediately understands this is a retrieval of competitor data, distinct from the audit-running siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when NOT to expect action: 'Ne déclenche PAS de nouvelle analyse', which routes the agent away from expecting a fresh run. It doesn't name a specific alternative tool for generating an analysis, so it is clear but not fully routing-complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_editorial_calendarRead a site's editorial calendarA
Lit le calendrier éditorial LightSpot d'un site sur une période : créneaux importés, contenus en préparation, planifiés ou publiés, et prochaines exécutions autopilot.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Fin exclue de la période, au format ISO 8601 avec fuseau (366 jours maximum). | |
| from | Yes | Début inclus de la période, au format ISO 8601 avec fuseau. | |
| siteId | Yes | Identifiant du site LightSpot. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It usefully enumerates what the calendar contains (imported slots, in-preparation/planned/published content, upcoming autopilot runs), which hints at a read-only operation, but it never states permissions, pagination, volume limits, or whether the returned data is cached/live.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that moves from the operation to the scope to the contents of the response. It is dense but every clause carries information; only the trailing enumeration of content states feels slightly list-like.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description is the only source describing the payload, and it does list the content categories returned. It stops short of describing the shape of those entries or whether results are grouped by day/slot, which leaves a modest gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so siteId, from, and to are already fully documented in the schema, including the ISO 8601 format and the 366-day cap. The description only gestures at 'une période' and adds nothing beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Lit') and resource ('calendrier éditorial LightSpot d'un site'), and it scopes the operation to a period. It does not explicitly contrast itself with the sibling create_editorial_calendar, but 'Lit' vs 'create' makes the distinction inferable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can gather this is the read side of the calendar pair, but there is no statement of when to prefer it, what prerequisites exist (e.g. site access), or what to do instead when the calendar must be modified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_expert_reportGet a site's expert reportA
Récupère le dernier rapport de nos 8 experts (SEO technique, qualité éditoriale, SEO/GEO, données structurées, sitemaps, performance, analyse visuelle, autorité de marque) produit après un audit d'un site : constats priorisés, actions recommandées avec leurs étapes, limites et artefacts prêts à appliquer (JSON-LD, sitemap…). Résumé par défaut (constats + actions) ; full=true ajoute la justification des actions, les limites, les artefacts et les preuves ; expert=… limite la lecture à un seul expert (utile avec full=true pour lire un chapitre complet sans tout charger). auditId cible l'analyse d'un audit précis, sinon la plus récente du site. Ne déclenche PAS d'analyse — si aucune n'existe, renvoie status: "NONE" ; PENDING/RUNNING = réessayer plus tard.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | true pour le rapport complet (justifications, limites, artefacts, preuves), sinon un résumé. | |
| expert | No | Ne renvoyer que ce chapitre d'expert. | |
| siteId | Yes | Identifiant du site LightSpot. | |
| auditId | No | Identifiant d'un audit précis (sinon la dernière analyse du site). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full load, and it does so well: it discloses that it never triggers an analysis, that a missing analysis yields status "NONE", that in-progress states require a retry, and that full/expert change payload size. It does not mention permissions or rate limits, but the state-machine behavior is a genuinely useful disclosure beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then parameter behavior, then the non-trigger/status semantics, and every sentence carries information. The enumeration of eight experts is long but legitimately informative; the single dense paragraph is slightly harder to scan than a structured layout would be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description fills most gaps: it describes the returned content (findings, actions, limits, artifacts, proofs) and the status outcomes. It is nearly complete for a report-retrieval tool, though the exact shape of the "NONE/PENDING/RUNNING" response and any pagination are not spelled out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: full=true adds justification/limits/artifacts/proofs on top of the default summary, expert limits reading to one chapter and is "utile avec full=true", and auditId chooses a specific analysis versus the site's most recent one. This augments rather than repeats the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
It opens with a specific verb ("Récupère") and resource ("le dernier rapport de nos 8 experts"), enumerates the eight expert chapters, and details exactly what each report contains (constats priorisés, actions, artefacts). An agent can distinguish this read-only report fetcher from siblings like run_audit or get_audit without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context and an explicit when-not: "Ne déclenche PAS d'analyse", plus the retry condition "PENDING/RUNNING = réessayer plus tard", and when to use expert with full. It stops short of naming the sibling to call instead (e.g. run_audit) to trigger an analysis, so it is strong but not fully explicit about the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_siteGet a siteC
Métadonnées d'un site et ses audits récents.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Identifiant du site. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it discloses very little. 'Get' implies a safe read, but there is no mention of permissions, how many 'récents' audits are returned, pagination, or error behavior when the id is unknown.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with the resource and payload front-loaded and no filler. It is efficient, though its brevity is partly what leaves the behavioral and routing gaps.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter getter with no output schema, the description does state what comes back (metadata and recent audits), which is the minimum an agent needs. It remains thin on the depth of that payload and on how this tool relates to the audit-oriented siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there is only one parameter, the site id, already documented in the schema as 'Identifiant du site.' The description adds no format, source, or lookup guidance beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (un site) and states the returned payload (métadonnées + audits récents), which is more than the tautological title 'Get a site'. It implicitly distinguishes itself from list_site_audits and get_audit by bundling metadata with recent audits, but does not name those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to call get_site versus list_sites, get_audit, or list_site_audits, and no prerequisites such as needing a valid site id. With ten sibling tools, the absence of routing guidance is a real gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_site_auditsList a site's audit historyC
Historique paginé des audits d'un site.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Identifiant du site. | |
| limit | No | Taille de page (défaut 50). | |
| offset | No | Décalage de pagination. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses pagination, but that is already encoded in limit/offset, and says nothing about read-only nature, permissions, ordering, or what an empty history means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no waste and the key concept (audit history) front-loaded. It is efficient, though at this length it is arguably under-specified rather than optimized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity three-parameter list tool with no output schema, the description is minimally adequate, but with no annotations and no mention of read-only behavior or return shape it leaves gaps an agent must fill by inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents id, limit, and offset semantics. The description's 'paginé' merely confirms the pagination parameters without adding format or defaulting detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource: a paginated history of audits for a site. It maps cleanly onto the tool name and title, but does not distinguish itself from siblings such as get_audit, get_audit_status, or audit_and_wait, which also concern audits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no indication of when to use this tool versus get_audit or get_audit_status, nor any prerequisite or exclusion guidance. The word 'paginé' hints at browsing many audits, but the agent must infer that itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_sitesList your sitesA
Liste paginée des sites enregistrés sur votre compte LightSpot (avec leur dernier score).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Taille de page (défaut 50). | |
| offset | No | Décalage de pagination. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose pagination and that each entry carries a latest score, and 'liste' implies a read-only operation, but it says nothing about ordering, total-count behavior, auth requirements, or rate limits. Adequate but thin for a tool with zero structured behavioral metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no waste; the core action is front-loaded and the parenthetical detail about the latest score is placed where it does not interrupt the main claim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter list tool with no output schema and no annotations, the description covers what the resource is and one notable payload property. It could still note ordering or result volume, but nothing an agent needs to invoke it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so limit and offset are already documented in the schema (including the default of 50). The description adds only the word 'paginée', which restates the schema rather than adding semantics. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Liste paginée des sites') and adds scope ('enregistrés sur votre compte LightSpot') plus an extra payload detail ('avec leur dernier score'). The plural 'sites' naturally contrasts with the sibling 'get_site', but the description never names the alternative, so differentiation is implicit rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: it is a listing tool, so an agent can infer it is for browsing all sites rather than fetching one. There is no statement of when to prefer this over get_site or list_site_audits, no prerequisites, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_auditStart an audit (non-blocking)A
Démarre un audit SEO & GEO sur une URL sans attendre. Renvoie l'id et le statut. Utilisez get_audit_status pour suivre, get_audit pour les résultats.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL à auditer. | |
| siteId | No | Rattacher l'audit à un site existant (optionnel). | |
| maxPages | No | Nombre de pages à crawler. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden. It usefully discloses the async/non-blocking behavior and that the response contains an id and status. It does not mention permission/auth requirements, rate limits, cost, or crawl constraints, which leaves meaningful behavioral gaps for a tool that launches a crawling job.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with zero filler; the non-blocking behavior and return value are front-loaded before the routing hints. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description partially compensates by naming the return payload (id, statut). For a job-launching tool with no annotations, the async contract and follow-up path are covered, though callers get no guidance on permissions or failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema itself documents url, siteId and maxPages adequately. The description only restates the URL ('sur une URL') and adds no format, default, or bounds detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Démarre/Starts) and resource (audit SEO & GEO sur une URL), plus the key modifier 'sans attendre' that separates it from the sibling audit_and_wait. An agent can tell it apart from both the blocking variant and the read-only status tools without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes follow-up work: 'Utilisez get_audit_status pour suivre, get_audit pour les résultats.' That is clear when-to-use guidance for the downstream calls. It does not, however, state when to prefer this over audit_and_wait, so the alternative selection is left to inference from 'sans attendre'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
11 tool updates
v0.4.1- First observed
audit_and_wait - First observed
create_editorial_calendar - First observed
get_audit - First observed
get_audit_status - First observed
get_competitors - First observed
get_editorial_calendar - First observed
get_expert_report - First observed
get_site - First observed
list_site_audits - First observed
list_sites - First observed
run_audit
TDQS
Scored across 11 tools
Most tools have clearly distinct purposes: run_audit vs audit_and_wait (async vs blocking), get_audit_status (lightweight) vs get_audit (full results), and get_editorial_calendar vs create_editorial_calendar (read vs write) are well-separated by their descriptions. Minor overlap exists between get_audit and get_expert_report (both surface audit-derived output) and between get_site and list_site_audits, but the descriptions clarify the boundaries.
Ten of eleven names follow a predictable verb_noun pattern (get_*, list_*, run_audit, create_editorial_calendar), which is highly consistent. The lone deviation is audit_and_wait, which inverts to a noun_and_verb compound and breaks the otherwise uniform convention.
Eleven tools is a well-scoped set for an SEO/GEO audit platform, comfortably within the ideal 3-15 range. Each tool earns its place by covering a distinct phase: audit triggering, polling, results retrieval, site lookup, and calendar management.
The audit lifecycle is well covered (trigger, poll, fetch, expert report, wait convenience), and the editorial calendar supports read plus idempotent import. Gaps remain in write operations for sites (no create/delete) and the inability to trigger a new competitor analysis or delete calendar slots, but these are workable given the read-heavy workflow.
Maintenance
Related MCP Connectors
Run SEO + AI-visibility (GEO) audits from Claude, Cursor & other AI clients.
Open-source AI SEO over MCP: audits, ranks, keywords, backlinks + AI visibility (GEO).
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
AI visibility reports, competitor insights, readiness audits, and GEO content workflows.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables SEO audits and URL monitoring via the SEO Radar API from any MCP-compatible AI client.77 npmMIT
- -licenseNot gradedqualityCmaintenanceEnables AI assistants to perform comprehensive SEO and GEO measurements, including site audits, keyword research, ranking tracking, and brand visibility analysis across search engines and generative AI platforms.-
- AlicenseAqualityBmaintenanceExposes OptiQra's full SEO/GEO/AEO audit and AI-fix/insight tools as MCP tools for AI clients like Claude, Cursor, and Windsurf. Use natural language to crawl URLs, analyze performance/a11y/security, and generate AI-driven fixes and strategy insights.429 npmMIT
- AlicenseAqualityBmaintenanceEnables AI assistants to run live SEO/readiness audits against 50+ AI crawlers, validate schema and robots.txt, and generate llms.txt, robots.txt, and JSON-LD files directly from MCP-compatible clients like Claude Desktop and Cursor.8728 npmMIT