Skip to main content
Glama
Sign In
answerbeacon

answerbeacon

by iskra-astudillo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

answerbeacon-check

See what AI search tools can read on a page, and get a copy-paste fix for every miss.

ChatGPT, Perplexity, Claude and Gemini answer questions that used to go to a list of links. They can only quote what they can read. answerbeacon-check fetches one page, scores it against 20 on-page elements those tools and search engines rely on (titles, descriptions, headings, JSON-LD, FAQ, breadcrumbs, calls to action and more), shows the evidence for every result, and generates the markup to fix each miss.

It is a CLI and a local MCP server. Pure Python standard library, no API keys, no account.

$ answerbeacon-check eliteagenticsolutions.com
https://eliteagenticsolutions.com  score 16/20
  PASS  1. SEO Page Titles — 'Elite Agentic Solutions — Governable AI Agents' (52 chars)
  PASS  2. Meta Descriptions — 'A five-agent engine with a hash-chained audit trail and rule engine on every a
  PASS  3. Keyword Rich H1s — 1 <h1> found: ['Ship AI Agents Any Business CanAudit, Govern, and Trust.']
  MISS  5. Image Alt Text — 1 imgs, 0 with alt (0%)
  MISS 10. Location Pages — no location page link
  MISS 16. Customer Reviews — JSON-LD types present: ['Answer', 'Brand', 'BreadcrumbList', 'ContactPoint', 'FA
  MISS 20. Helpful Blog Content — no blog link; JSON-LD types: ['Answer', 'Brand', 'BreadcrumbList', 'ContactP
  ...  (PASS lines for the other elements trimmed)

That is a real run against our own site on 2026-11-04, misses included.

Install

pipx install git+https://github.com/iskra-astudillo/answerbeacon-check
# or, from a clone:
python -m answerbeacon_check example.com

Python 3.8 or newer. No dependencies.

Related MCP server: agentbuilt

Use

answerbeacon-check example.com                  # human report
answerbeacon-check example.com --json           # full report with evidence and fixes
answerbeacon-check example.com --fixes-out fixes/   # one file per fix (JSON-LD, meta tags, robots.txt, sitemap.xml)
answerbeacon-check example.com --min-score 18   # exit 1 below 18: a CI gate for your marketing site
answerbeacon-check example.com --no-robots      # skip the robots.txt check (only for sites you own)

Exit codes: 0 scanned, 1 below --min-score, 2 the page could not be read.

MCP server

answerbeacon-check mcp starts a stdio MCP server with two tools:

Tool

What it does

audit_page(url)

Runs the audit and returns the JSON report: score, evidence per element, fixes.

explain_check(check)

Explains what one element (e01_title … e20_blog) looks for.

Claude Code

claude mcp add answerbeacon -- answerbeacon-check mcp

Claude Desktop / Cursor (claude_desktop_config.json or .cursor/mcp.json)

{
  "mcpServers": {
    "answerbeacon": { "command": "answerbeacon-check", "args": ["mcp"] }
  }
}

Then ask your agent: "Audit example.com for AI-search readiness and apply the fixes to our templates." The repo also ships a SKILL.md that tells an agent how to apply fixes without inventing facts.

The 20 elements

#

Element

Passes when

1

Page title

<title> present, 15–70 characters

2

Meta description

meta name="description", 50–180 characters

3

H1

exactly one <h1>, at least 10 characters

4

Internal links

at least 5 distinct internal links

5

Image alt text

at least 80% of <img> carry alt text

6

FAQ section

a visible FAQ heading

7

FAQ schema

JSON-LD FAQPage

8

Local keywords

locality phrases in body copy ("serving", "based in", …)

9

Service pages

a link to /services, /solutions, /products or /pricing

10

Location pages

a link to /locations, /areas-we-serve or /service-area

11

Breadcrumbs

BreadcrumbList JSON-LD or a breadcrumb nav

12

Organization schema

Organization, Corporation, SoftwareApplication or WebSite

13

Local business schema

LocalBusiness or a subtype

14

Service schema

Service, Product or Offer

15

Author bios

Person schema or an author or team byline

16

Reviews

Review / AggregateRating schema or a testimonials block

17

Case studies

case-study or success-story content

18

Related content

a related-reading block

19

Call to action

an explicit CTA phrase in visible text

20

Blog

a link to /blog, /articles, /resources, /insights, /guides or Article schema

Every element in the JSON report carries what (what was searched for) and found (what was actually seen), so you can check any verdict yourself.

A second, non-scored block (hygiene_checks) covers single-page technical hygiene: title and description length, multiple H1s, skipped heading levels, thin content, noindex, canonical pointing elsewhere, redirect chains and slow responses. Its taxonomy is adapted from every-app/open-seo (MIT); see NOTICE.

Fixes that refuse to lie

Fixes are generated per miss: title and meta templates, Organization, Service and BreadcrumbList JSON-LD, Open Graph tags, robots.txt, sitemap.xml and a canonical link. Two guardrails are built in:

  • No FAQPage schema without a visible FAQ. Google treats it as structured-data spam, so the fix says to write the visible FAQ first.

  • No LocalBusiness schema without a real address on the page. Emitting it would assert premises that do not exist.

Safety

  • One bounded fetch of the page, plus robots.txt and sitemap.xml. Hard timeout (8 s), 2 MB byte cap, at most 3 redirects.

  • SSRF guard. Every hop is resolved and refused if it points at private, loopback, link-local, reserved or multicast space, so the MCP tool cannot be used to probe your network or a cloud metadata endpoint.

  • Respects robots.txt. A Disallow: / for * or for this tool stops the scan.

  • Fails closed. An unreachable, blocked or non-HTML page returns ok: false with an error class and score: null. It never returns a number it did not measure.

What it does not do

It does not query ChatGPT, Perplexity or any other assistant, and it does not promise that a page will be cited. It checks whether the page gives those tools something clear to read. Treat the score as a work list, not a ranking.

Design notes

  • Evidence over booleans. An early internal version required quoted attributes and missed <meta name=description content=...> on minified pages. Attribute parsing now accepts unquoted values, and every result carries the string it matched, so a false negative is visible in the report.

  • Fix next to the failure. Each check that can fail has a generated fix, so the output is a task list rather than a grade.

  • Score stability. Hygiene checks were added as a separate block so that "20/20" keeps meaning the same thing across versions.

Hosted version

AnswerBeacon runs the same audit in the browser, re-audits on a schedule and attributes AI-crawler visits to the company behind each bot.

License

MIT. See LICENSE and NOTICE.

Available Tools

2 tools
audit_pageA

Fetch one public web page (bounded, SSRF-guarded, robots-respecting) and score it against 20 on-page elements that AI search tools read. Returns the evidence for every element and a copy-paste fix for every miss. Fails closed: an unreadable page returns no score.

NameRequiredDescriptionDefault
urlYesDomain or URL, e.g. example.com

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations supplied, the description carries the full burden and does well: it discloses SSRF guarding, robots.txt compliance, bounded fetching, and a fail-closed policy where an unreadable page yields no score. The return contract is also described (evidence per element, copy-paste fix per miss). What remains unstated is rate limiting, timing, and whether a robots-disallowed page counts as 'unreadable' under the fail-closed rule.

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

Conciseness5/5

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

Three sentences, each earning its place: capability, return shape, failure mode. The parenthetical guard clauses are compressed efficiently and the fail-closed rule is placed last where it reads as a caveat. No filler or repetition of the tool name.

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?

With no output schema, the description steps in to describe what comes back: per-element evidence plus a fix for every miss. The fail-closed behavior closes the main edge case. Slightly incomplete on robots-disallowed handling and on the fact that there is no sibling cross-reference, but the essential picture is there for a one-parameter tool.

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?

Schema coverage is 100% and there is a single required url parameter whose schema description already gives the accepted form ('Domain or URL, e.g. example.com'). The prose adds nothing further about the parameter, so the schema does the work; baseline 3 applies. It does not clarify whether a bare domain gets a protocol prepended or which page is audited in that case.

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?

The description uses a specific verb pair (fetch and score) against a specific resource (one public web page) and names the exact framework applied: 20 on-page elements that AI search tools read. That is unambiguous. It does not reference the sibling tool explain_check, so the agent gets no explicit differentiation between auditing a page and explaining a single check.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: 'one public web page' signals the single-page scope and the 'public' qualifier implicitly excludes internal or authenticated pages. There is no explicit guidance on when to choose audit_page over explain_check, and no statement of prerequisites or limits beyond the word 'bounded'. An agent can infer the use case but must guess at the boundaries.

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

explain_checkA

Explain what one of the 20 elements (e01_title ... e20_blog) looks for.

NameRequiredDescriptionDefault
checkYesElement id, e.g. e07_faq_schema

TDQS

A3.5/5.0
Behavior2/5

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

No annotations are supplied, so the description carries the full disclosure burden, yet it says nothing about whether this is read-only, what form the explanation takes (prose vs structured), or how a bad element id is handled. The only behavioral hint is the finite set of 20 elements, which does imply a bounded, non-mutating lookup.

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

Conciseness5/5

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

A single front-loaded sentence with no filler; the verb, the resource, and the valid identifier space all appear immediately.

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 one-parameter, non-destructive lookup with no output schema, the definition covers what is needed to invoke it correctly. Minor gaps are the unexplained return format and the drift between "check" in the name/parameter and "element" in the description.

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

Parameters4/5

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

Schema coverage is 100% with an example id, and the description still adds value by disclosing the full domain: exactly 20 elements, ranging from e01_title to e20_blog. That count and range tell the agent which ids are valid, beyond the single schema example.

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?

The description pairs a specific verb ("Explain") with a bounded resource (one of the 20 elements) and enumerates the ID space, so the agent knows exactly what it gets back. It never mentions the sibling audit_page, so the distinction between 'explain a check' and 'run the audit' is left to inference.

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

Usage Guidelines3/5

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

Usage is only implied: an agent can gather that this is for learning what a check tests, presumably before or after running audit_page. There is no explicit when-to-use statement, no exclusion, and no mention of the alternative tool by name.

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.

  1. 2 tool updatesv0.1.0
    • First observedaudit_page
    • First observedexplain_check
Deploy Server
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

TDQS

A3.8/5.0

Scored across 2 tools

Disambiguation5/5

audit_page performs the scoring action on a URL, while explain_check only describes a single element's criteria; there is no plausible way to confuse the two. Each tool also has a distinct return shape (score plus evidence vs. explanatory text).

Naming Consistency5/5

Both names use the same snake_case verb_noun pattern (audit_page, explain_check), with clear, concrete verbs. No mixed conventions or vague catch-all names.

Tool Count3/5

Two tools is on the thin side, though they map cleanly to the only two actions implied by the domain (score a page, explain a criterion). The surface feels borderline minimal rather than over- or under-built for a single-purpose auditor.

Completeness4/5

The core lifecycle—run an audit and look up what each of the 20 checks means—is covered, and audit_page returns evidence plus fixes for every element, so there are few dead ends. A minor gap: there is no tool to enumerate e01...e20, so an agent must obtain IDs from audit output or guess them.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • agentbuilt

    agentbuiltofficial

    agentbuilt
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to run a free AI-readiness audit of any URL, checking AI crawler rules, JavaScript-free page text, JSON-LD, llms.txt, sitemap, meta description, FAQ schema, and returning a score with findings and fixes. Also exposes the same capability via an A2A agent endpoint.
    MIT

  • creavores-aeo-mcp

    tresor4k
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables auditing any URL for AEO and AI-search readiness, including direct-answer citability, JSON-LD validity, llms.txt compliance, E-E-A-T signals, agentic crawlability, citation simulation, and competitor score comparisons.
    95 npm
    MIT