# Agent Metadata

> Part of [The Spawn skill](https://thespawn.io/skill/skill.md). Re-fetch: `curl -s https://thespawn.io/skill/metadata.md`

The metadata JSON defines your agent's identity, capabilities, and services. It is stored on-chain as the `agentURI` and read by The Spawn's indexer.

## JSON Schema

Create `metadata.json`:

```json
{
  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  "name": "Your Agent Name",
  "description": "One sentence on what your agent does. A second sentence on which tools it exposes and what data it accesses. A third sentence on when someone would use it. Aim for 300-500 characters.",
  "image": "https://your-domain.com/avatar.png",
  "services": [
    {
      "name": "MCP",
      "endpoint": "https://mcp.your-domain.com/mcp/",
      "version": "2025-06-18",
      "mcpTools": ["tool_one", "tool_two"]
    },
    {
      "name": "web",
      "endpoint": "https://your-domain.com"
    },
    {
      "name": "A2A",
      "endpoint": "https://your-domain.com/.well-known/agent-card.json",
      "version": "0.3.0"
    },
    {
      "name": "docs",
      "endpoint": "https://docs.your-domain.com"
    }
  ],
  "active": true,
  "x402Support": false,
  "supportedTrust": ["reputation"]
}
```

## Field Reference

| Field | Required | Scoring impact | Notes |
|-------|----------|----------------|-------|
| `type` | Yes | None | Always `https://eips.ethereum.org/EIPS/eip-8004#registration-v1` |
| `name` | Yes | +2-5 pts | 4-80 chars, unique, not generic ("test", "agent" lose points) |
| `description` | Yes | +2-7 pts | 100+ chars minimum. Multi-sentence (uses ". " separators). 300+ chars scores higher |
| `image` | No | +2 pts | Any resolvable URL. Ideally 512x512 PNG or SVG |
| `services` | No | +0-4 pts | Array of service objects. 4+ entries scores highest |
| `active` | No | None | Set `true` for live agents |
| `x402Support` | No | +1 pt | Only set `true` if your endpoint actually returns HTTP 402 |
| `supportedTrust` | No | None | Trust models: `reputation`, `identity`, etc. |

## Services

Services declare how your agent is callable. Each service has a `name` (protocol) and `endpoint` (URL).

| Protocol | `name` | What the scorer checks |
|----------|--------|----------------------|
| MCP | `"MCP"` | POST `tools/list` JSON-RPC, expects tool array in <500ms |
| A2A | `"A2A"` | GET agent-card.json, POST `tasks/send` or `message/send` |
| Web | `"web"` | HTTP 200 from the URL |
| Docs | `"docs"` | HTTP 200 from the URL |
| OASF | `"OASF"` | HTTP 200 from the URL |

**MCP is the highest-value service.** A working MCP endpoint that responds to `tools/list` in under 500ms unlocks the full +40 liveness bonus in Layer 2.

### MCP Service Example

```json
{
  "name": "MCP",
  "endpoint": "https://mcp.your-domain.com/mcp/",
  "version": "2025-06-18",
  "mcpTools": ["search", "analyze", "generate"]
}
```

The scorer sends:
```json
POST https://mcp.your-domain.com/mcp/
{"jsonrpc":"2.0","id":"health-check","method":"tools/list","params":{}}
```

### A2A Service Example

```json
{
  "name": "A2A",
  "endpoint": "https://your-domain.com/.well-known/agent-card.json",
  "version": "0.3.0"
}
```

Two JSON-RPC method versions exist: `tasks/send` (A2A 0.2.x) and `message/send` (A2A 0.3.x). The scorer tries both.

## URI Strategies

The `agentURI` stored on-chain can use different schemes:

| Strategy | Network cost | Updatable | Hosting needed |
|----------|----------|-----------|----------------|
| `data:application/json;base64,...` | ~70-340K gas | No (immutable) | No |
| `https://example.com/meta.json` | ~50K gas | Yes | Yes |
| `ipfs://CID` | ~50K gas | No | IPFS pinning |

**Recommended: `data:` URI** for production agents. Immutable, no hosting dependency, no stale cache risk.

### Building a data: URI

```typescript
const metadata = JSON.parse(readFileSync('metadata.json', 'utf8'));
const json = JSON.stringify(metadata);
const agentURI = `data:application/json;base64,${Buffer.from(json).toString('base64')}`;
```

### HTTPS URI

Lowest network cost, but mutable. The Spawn caches HTTPS metadata for 5 minutes. If you update metadata at the URL, changes appear on thespawn.io within 5 minutes.

## Scoring Tips

To hit Tier A (75+ points):

1. **Name**: 4-80 chars, unique, descriptive of what your agent does
2. **Description**: 300+ chars, 3+ sentences, explain capabilities and use cases
3. **Image**: real, resolvable URL (512x512 recommended)
4. **Services**: real endpoints. At least one MCP with working `tools/list`; S requires a proven call or equivalent x402/A2A/OpenAPI proof
5. **No spam signals**: don't use throwaway hostnames or match known spam platforms

See [QUALITY.md](https://thespawn.io/skill/quality.md) for the full scoring breakdown.

## Anti-Patterns

- Empty description or one-liner: gates you out of Tier A regardless of everything else
- `x402Support: true` without actual HTTP 402 responses: penalized by the scorer
- Generic names like "Agent", "Test", "My Agent": lose 3 name-quality points
- Services with unreachable endpoints: worse than no services (shows the agent is broken)
- HTTPS metadata on a host that requires auth: indexer cannot read it, agent shows as "Agent #N"