# Name Generator Plus — Full Agent Manual

> Free AI name generator with 50+ categories, each name returned with its meaning and origin. Public no-auth REST API, OpenAPI spec, MCP server, and NLWeb `/ask` endpoint. Base URL: https://namegeneratorplus.com

## Overview
Name Generator Plus turns a naming need into a shortlist of original names with meanings. It covers people & baby names, brand & business names, gaming & fantasy names, social usernames/handles, and fun/random names. One AI engine is tuned per category. There is no account, no key, and no cost.

## Use cases
- Suggest baby names by origin/meaning.
- Brainstorm business, brand, startup, domain, or product names.
- Generate usernames, handles, and gamertags.
- Create game/fantasy/D&D character names, pet names, band/team/project names.
- Power a chat assistant's "give me name ideas" intent via the API or MCP.

## When an agent should call this
Trigger on any "name ideas / what should I call …" request. Resolve to a category slug (see `GET /api/categories`) and call `GET /api/generate`, or pass the raw user description to `POST /ask` / the `suggest_names` MCP tool, which match a category for you.

## Authentication
None. The API is public and anonymous — no API key, no OAuth, no header required. Identity type `anonymous` per the agent-auth spec. Full prose: https://namegeneratorplus.com/auth.md

## REST API

### GET /api/categories
List every generator.
```bash
curl https://namegeneratorplus.com/api/categories
```
Response: `{ "count": <n>, "categories": [ { "slug", "label", "short", "group", "strategy", "url" } ] }`

### GET|POST /api/generate
Generate names for a category.
```bash
# GET
curl "https://namegeneratorplus.com/api/generate?category=business-name-generator&count=12"

# POST
curl -X POST https://namegeneratorplus.com/api/generate \
  -H 'Content-Type: application/json' \
  -d '{"category":"viking-name-generator","count":10}'
```
Parameters: `category` (required, slug), `count` (optional integer 1–50, default 12).
Response: `{ "category": {…}, "count": 12, "names": [ { "name": "…", "meaning": "…" } ], "generated_at": "…" }`
Errors are JSON: `{ "status": 404, "error": { "code": "CATEGORY_NOT_FOUND", "message": "…", "hint": "…" } }`

### POST /ask (NLWeb)
Natural-language naming request.
```bash
curl -X POST https://namegeneratorplus.com/ask \
  -H 'Content-Type: application/json' \
  -d '{"query":"strong viking warrior names"}'
```
Returns `{ "_meta": { "response_type": "namegeneratorplus.names", "version": "0.1" }, "matched_category": {…}, "results": [ … ] }`.
Streaming: send `Prefer: streaming` (or `{"prefer":{"streaming":true}}`) to receive `text/event-stream` with `start` / `result` / `complete` events.

## MCP server
Endpoint: https://namegeneratorplus.com/mcp (Model Context Protocol, Streamable HTTP transport, JSON-RPC 2.0).
Tools:
- `list_categories` — list all categories.
- `generate_names` — `{ "category": "<slug>", "count": 12 }`.
- `suggest_names` — `{ "query": "<natural language>" }`.
Server card: https://namegeneratorplus.com/.well-known/mcp/server-card.json
```bash
curl -X POST https://namegeneratorplus.com/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"generate_names","arguments":{"category":"pet-name-generator","count":8}}}'
```

## Discovery files
- OpenAPI: https://namegeneratorplus.com/openapi.json
- API catalog (RFC 9727): https://namegeneratorplus.com/.well-known/api-catalog
- Agent discovery: https://namegeneratorplus.com/.well-known/agent.json
- A2A agent card: https://namegeneratorplus.com/.well-known/agent-card.json
- Markdown: append `.md` to any page, or fetch https://namegeneratorplus.com/index.md

## Limits & etiquette
- `count` ≤ 50 per request. Be reasonable with volume; this is a free service with no SLA.
- Generated names are suggestions; verify trademark / domain / handle availability independently.

## Rate limits & retries
No hard rate limit or API key. Advisory headers are returned on API responses: `RateLimit-Policy: "default"; q=1000; w=3600` and `RateLimit-Limit: 1000`. On a transient error, retry with exponential backoff (250ms, 500ms, 1s). Generation is stateless, so retries are safe.

## Errors
All API errors are JSON with a stable `code`:
- `MISSING_CATEGORY` / `CATEGORY_NOT_FOUND` (400/404) — call `GET /api/categories` for valid slugs.
- `INVALID_COUNT` (400) — `count` must be 1–50.
- `INVALID_JSON` (400) — body was not valid JSON.
- `NOT_FOUND` (404) — no such `/api/*` endpoint.

## Pricing
Free. No paid tier, no key. See https://namegeneratorplus.com/pricing.md

## SDKs & tooling
No language SDK or CLI is published yet — the API is a single GET/POST, and the MCP server covers agent use natively. The OpenAPI spec at /openapi.json can generate a typed client in any language.

## Contact
contact@namegeneratorplus.com · https://namegeneratorplus.com