# reputation.md — Full Documentation

> Trust scoring infrastructure for AI agents. Scans /.well-known/agent.json,
> mcp.json, acp.json, /llms.txt, DNS _agent records, and TLS to classify
> domains as verified_agent, partial_agent, or not_detected and compute a
> 0-100 reputation score. Agents can query scores via MCP tools or REST API.
> No API key required.

## Overview

reputation.md is a free, open trust-scoring infrastructure layer for
the autonomous agent economy. When one AI agent needs to delegate work
to another — book a flight, sign a contract, move money — it must
first answer: can I trust this thing?

reputation.md provides that answer. Scan any agent domain and get back
a classification (verified_agent, partial_agent, or not_detected) plus
a score from 0-100 based on three passively-observable signals. No
signup. No API key. No cooperation from the target required. If an
agent publishes a protocol card at /.well-known/, it already has a score.

The project is part of the discover.md network.

## Problem Statement

Agents are about to move money, sign contracts, and book resources on
behalf of millions of businesses. The question is not whether autonomous
commerce happens — it is whether there is a trust layer underneath it
when it does.

Credit scores did not just measure trustworthiness. They made it
possible for strangers to do business. reputation.md does the same
thing at machine speed, for every permutation of agent-to-agent
commerce. The score is the primitive. Commerce is the emergent behavior.

## Agent Classification

Before computing a score, every scan classifies the domain into one
of three tiers based on what agent discovery endpoints it exposes:

### verified_agent
At least one protocol card (A2A /.well-known/agent.json, MCP
/.well-known/mcp.json, or ACP /.well-known/acp.json) is found and
has a valid schema. This is a real agent with structured discovery.
Full Honest signal scoring applies (up to 25/25).

### partial_agent
No protocol card found, but llms.txt or DNS _agent TXT records are
present. Signals intent to participate in the agent ecosystem but no
structured card yet. Full Honest signal scoring applies.

### not_detected
No agent discovery endpoints found. This is a regular website, not an
agent. The Honest signal is capped at 5/25 — there are no agent cards
to validate, so high honesty scores would be misleading.

Classification logic:
1. If ANY of [a2a, mcp, acp] probes are alive AND have valid schema → verified_agent
2. Else if ANY of [llms, ans] probes are alive AND valid → partial_agent
3. Otherwise → not_detected

## How Scoring Works

Every scan runs seven parallel probes against a domain, each with a
5-second timeout. The results are distilled into three weighted signals
that sum to a maximum of 100 points. Classification is computed before
scoring so the Honest signal cap can be applied.

### Signal 1: Alive (50 points, 50% weight)

Measures basic reachability of agent discovery endpoints. The score is
the percentage of probes that return a 2xx or 3xx HTTP status code,
scaled to 50 points.

Formula: (alive_probe_count / total_probe_count) * 50

A domain where all seven probes respond gets 50/50. A domain where
only the root and TLS respond gets ~14/50.

### Signal 2: Responsive (25 points, 25% weight)

Measures latency of agent protocol cards via the median (p50) time-to-
first-byte across all alive probes.

Scoring tiers:
- p50 ≤ 100ms → 25/25 (full marks)
- p50 ≤ 500ms → 12.5–25 (linear interpolation)
- p50 ≤ 2000ms → 0–12.5 (linear interpolation)
- p50 > 2000ms → 0/25

### Signal 3: Honest (25 points, 25% weight)

Validates whether agent discovery cards are schema-compliant and
whether declared capabilities match actual behavior. Three sub-factors:

- **Coverage** (40%): percentage of protocol endpoints that return valid
  JSON responses
- **Fields** (30%): percentage of available fields present in the
  response (e.g., name, url, skills for A2A; endpoints, capabilities
  for MCP)
- **Capabilities** (30%): percentage of declared capabilities that are
  actually implemented

Formula: (coverage * 0.4 + fields_ratio * 0.3 + caps_ratio * 0.3) * 25

**Important**: For domains classified as not_detected, the Honest score
is capped at 5/25. A domain with no agent card cannot score high on
honesty — there is nothing to validate.

### Grade Mapping

- **A**: score ≥ 90
- **B**: score ≥ 75
- **C**: score ≥ 50
- **F**: score < 50

### Design Principles

- No machine learning. No sentiment analysis.
- All signals are empirically observable from the public internet.
- Zero cooperation required from the target domain.
- Deterministic: same probes always produce the same score.
- Classification-aware: non-agents are scored fairly but cannot
  game the system by simply being fast.

## Protocol Probes

Seven probes run in parallel for every scan:

### A2A (Agent-to-Agent) — PROTOCOL CARD
- Endpoint: GET /.well-known/agent.json
- Spec: Google's Agent-to-Agent protocol
- Validates: name, url, description, skills array, version,
  provider, capabilities, authentication fields
- Finding a valid A2A card → verified_agent classification

### MCP (Model Context Protocol) — PROTOCOL CARD
- Endpoint: GET /.well-known/mcp.json
- Spec: Anthropic's Model Context Protocol
- Validates: mcp_version, name, endpoints, capabilities (tools,
  resources, prompts), tools array with inputSchema
- Finding a valid MCP card → verified_agent classification

### ACP (Agent Communication Protocol) — PROTOCOL CARD
- Endpoint: GET /.well-known/acp.json
- Validates: agent field presence, protocol metadata
- Finding a valid ACP card → verified_agent classification

### llms.txt — SIGNAL PROBE
- Endpoint: GET /llms.txt
- Spec: LLM-readable plain-text documentation
- Validates: presence of markdown headings, URLs, structured content
- Finding valid llms.txt → partial_agent classification (if no card)

### TLS
- Endpoint: HEAD / over HTTPS
- Validates: security headers including HSTS, CSP, X-Content-Type-Options,
  X-Frame-Options

### ANS (Agent Name Service) — SIGNAL PROBE
- Endpoint: DNS TXT lookup for _agent.{domain}
- Validates: presence of agent discovery TXT records
- Finding valid ANS records → partial_agent classification (if no card)

### HTTP Root
- Endpoint: HEAD /
- Validates: basic reachability, response time measurement

## Agent Access via MCP

MCP-compatible agents (Claude, GPT, etc.) can use reputation.md as a
tool without any API key. The MCP endpoint speaks JSON-RPC over HTTP.

### Discovery
- MCP card: GET https://reputation.md/.well-known/mcp.json
- MCP endpoint: POST https://reputation.md/api/mcp (JSON-RPC tools)
- GET https://reputation.md/api/mcp returns the MCP discovery card as JSON

### Available Tools

**get_agent_score** — Look up the cached reputation score for a domain.
Input: { "domain": "your-agent.ai" }
Returns: domain, classification, score, grade, signal breakdown,
protocols detected, first_seen, last_checked, scan_count, permalink.

**scan_agent** — Trigger a fresh scan of a domain. Rate limited.
Input: { "domain": "your-agent.ai" }
Returns: domain, classification, score, grade, signal breakdown,
protocols detected, elapsed_ms, permalink.

**list_agents** — Browse the agent directory. Returns all indexed agents.
Input: { "classification": "verified_agent" } (optional filter)
Returns: array of agent summaries with domain, classification, score,
grade, protocols, last_checked, scan_count, permalink.

### MCP Integration Example

To add reputation.md as an MCP tool source:
1. Fetch the discovery card at /.well-known/mcp.json
2. The card declares the endpoint at /api/mcp
3. Send JSON-RPC requests to POST /api/mcp
4. No authentication required. Stateless — no session management needed.

### JSON-RPC Initialize Example

```json
POST /api/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "my-agent", "version": "1.0" }
  }
}
```

### JSON-RPC Tool Call Example

```json
POST /api/mcp
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_agent_score",
    "arguments": { "domain": "your-agent.ai" }
  }
}
```

## REST API Reference

All endpoints support CORS. Read endpoints are publicly accessible.
Write endpoints require the domain to be sent in the request body.
No API key required.

### GET /api/agent/:domain
Returns the current cached score for a domain.

Response:
```json
{
  "domain": "your-agent.ai",
  "classification": "verified_agent",
  "score": 82,
  "grade": "B",
  "alive_score": 45.5,
  "responsive_score": 18.5,
  "honest_score": 18.0,
  "protocols": ["a2a", "mcp", "llms.txt"],
  "last_checked": "2025-01-15T10:30:00Z",
  "scan_count": 14
}
```

Cache: 5-minute CDN cache (s-maxage=300)

### GET /api/agent/:domain/history
Returns paginated scan history.

Query parameters:
- limit (default 50, max 200)
- before (ISO timestamp for cursor pagination)

Response: array of historical scan records with scores, classification,
and timestamps.

### GET /api/agent/:domain/probes
Returns detailed probe results from the latest scan.

Response: includes per-probe status, TTFB, validation results,
error messages, classification, and raw response metadata.

Cache: 1-minute CDN cache

### POST /api/scan
Triggers a fresh real-time scan.

Request:
```json
{ "domain": "your-agent.ai" }
```

Response:
```json
{
  "domain": "your-agent.ai",
  "classification": "verified_agent",
  "score": 82,
  "grade": "B",
  "signals": {
    "alive": { "score": 45.5, "max": 50 },
    "responsive": { "score": 18.5, "max": 25 },
    "honest": { "score": 18.0, "max": 25 }
  },
  "protocols": ["a2a", "mcp"],
  "elapsed_ms": 1245,
  "permalink": "https://reputation.md/agent/your-agent.ai"
}
```

Rate limit: 5 requests per minute per IP.
Returns 429 with Retry-After header when exceeded.

### GET /api/directory
Returns all indexed agents (verified_agent and partial_agent) with enriched
metadata including agent endpoints, tools, and skills extracted from protocol cards.

Query parameters:
- classification (optional): "verified_agent" or "partial_agent"
- format (optional): "text" for categorized markdown output (same as Accept: text/plain)

Content negotiation:
- Accept: application/json (default) → JSON response
- Accept: text/plain (or ?format=text) → categorized markdown listing, ideal for agents

JSON response:
```json
{
  "agents": [
    {
      "domain": "your-agent.ai",
      "name": "Your Agent",
      "description": "An AI assistant for tasks",
      "classification": "verified_agent",
      "score": 82,
      "grade": "B",
      "protocols": ["a2a", "mcp", "llms.txt"],
      "endpoints": {
        "a2a_card": "https://your-agent.ai/.well-known/agent.json",
        "a2a_url": "https://your-agent.ai/a2a",
        "mcp_card": "https://your-agent.ai/.well-known/mcp.json",
        "mcp_server": "https://your-agent.ai/mcp/sse",
        "llms_txt": "https://your-agent.ai/llms.txt"
      },
      "tools": ["search", "summarize"],
      "skills": ["web-search", "document-qa"],
      "last_checked": "2026-02-06T04:37:15Z",
      "scan_count": 4
    }
  ],
  "total": 1
}
```

Text format response (?format=text):
```
# reputation.md Agent Directory
> 253 agents indexed. Scanned across A2A, MCP, ACP, llms.txt, DNS, and TLS.

## Verified Agents (1)
### Your Agent — 82/B
An AI assistant for tasks
- a2a_card: https://your-agent.ai/.well-known/agent.json
- mcp_server: https://your-agent.ai/mcp/sse
- tools: search, summarize
- scorecard: https://reputation.md/agent/your-agent.ai
```

Cache: 5-minute CDN cache (s-maxage=300)

### GET /api/badge/:domain.svg
Returns an embeddable SVG badge showing the domain's current score
and grade.

Usage in markdown:
```
![reputation.md score](https://reputation.md/api/badge/your-agent.ai.svg)
```

Cache: 1-hour CDN cache (s-maxage=3600)

## Agent Discovery

reputation.md itself implements the protocols it scans, serving as
both a scanner and a discoverable agent:

- A2A card: https://reputation.md/.well-known/agent.json
- MCP card: https://reputation.md/.well-known/mcp.json
- ACP card: https://reputation.md/.well-known/acp.json
- MCP tools: https://reputation.md/api/mcp (GET = discovery card, POST = JSON-RPC)
- Agent directory: https://reputation.md/api/directory (JSON) or ?format=text (markdown)
- LLM docs: https://reputation.md/llms.txt
- Full docs: https://reputation.md/llms-full.txt

### A2A Skills
- **score-lookup**: Returns current reputation score for any domain
- **score-history**: Returns paginated score history
- **fresh-scan**: Triggers a new scan and returns computed score

### MCP Tools
- **get_agent_score**: Look up reputation score and classification for a domain
- **scan_agent**: Trigger a fresh scan (rate limited to 5/min)
- **list_agents**: Browse the agent directory (optionally filter by classification)

## Architecture

- **Web app**: Next.js on Vercel, handles user-initiated scans in
  real time with immediate results
- **MCP endpoint**: /api/mcp, stateless JSON-RPC handler for
  agent-to-agent tool calls
- **Scan worker**: Background Railway service, processes queued scan
  jobs in batches
- **Cron scheduler**: Background Railway service, re-scans monitored
  domains on a configurable schedule to keep scores fresh
- **Database**: Supabase (PostgreSQL) with row-level security

### Data Model
- **agents**: Primary directory of scored domains (score, grade,
  classification, signals, protocols, scan history)
- **scans**: Individual scan records with full probe data and classification
- **score_changes**: Audit log tracking grade changes, classification
  changes, score shifts, and protocol additions/removals
- **scan_queue**: Background job queue for worker processing

## Use Cases

### Pre-flight Trust Check
Before an agent delegates a task, query the score:
```
GET https://reputation.md/api/agent/vendor-agent.ai
```
If classification is not_detected or score < 75, route to a different provider.

### Agent Marketplace Listings
Display trust badges and classification next to agent listings so
buyers can compare reliability at a glance. verified_agent badge
signals real protocol compliance.

### CI/CD Quality Gate
Add a step to your deployment pipeline that checks your own agent's
score and classification. Fail the build if score drops below a
threshold or classification changes unexpectedly.

### Agent-to-Agent Discovery
Before calling another agent's MCP tools or A2A skills, check their
reputation score via the MCP tool endpoint. This adds a trust layer
to any agent delegation chain.

### Compliance & Procurement
Generate a trust report for any AI agent your organization is
evaluating. Classification shows whether it's a real agent with
protocol cards or just a website.

## FAQ

**Does the target domain need to opt in?**
No. All probes hit publicly-accessible endpoints (/.well-known/,
/llms.txt, DNS, HTTPS). Zero cooperation required.

**What makes something a "verified agent"?**
Having at least one valid protocol card at /.well-known/agent.json,
/.well-known/mcp.json, or /.well-known/acp.json. The card must parse
as valid JSON and contain the required schema fields.

**What if a domain has no agent protocols?**
It gets classified as not_detected. It still receives an Alive and
Responsive score, but the Honest signal is capped at 5/25 since there
are no agent cards to validate. This means regular websites (google.com,
wikipedia.org) get lower scores than real agents, which is by design.

**How often are scores updated?**
User-initiated scans are always fresh (real-time). Monitored domains
are automatically re-scanned on a configurable schedule. You can trigger
a fresh scan any time via the REST API or MCP scan_agent tool.

**Is the scoring deterministic?**
Yes. The same set of probe responses always produces the same score.
No ML models, no random factors.

**Do I need an API key?**
No. All endpoints (REST and MCP) are free and keyless. Rate limits
apply to scan endpoints (5/min per IP).

**Can I embed the score badge?**
Yes. Use: ![score](https://reputation.md/api/badge/your-agent.ai.svg)

**How do I add reputation.md as an MCP tool?**
Point your MCP client at https://reputation.md/api/mcp. Discovery card
is at /.well-known/mcp.json (also returned by GET /api/mcp). Three tools
available: get_agent_score, scan_agent, and list_agents. No authentication
needed.

## Contact

- Website: https://reputation.md
- About: https://reputation.md/about
- Network: https://discover.md
- Twitter: https://x.com/smrt_cntrct