# NamingSignal agent guide NamingSignal is an evidence-first product-naming workflow available through a hosted remote MCP endpoint, a read-only stdio MCP package, a local CLI, and composable REST endpoints. ## Authentication The documentation, OpenAPI contract, agent guide, and health route are public. Every POST API route requires either a signed-in Clerk browser session or a user-owned NamingSignal API key in the Authorization Bearer header. Create and revoke keys at https://namingsignal.com/developers/keys. CLI and stdio MCP clients read NAMING_SIGNAL_API_KEY from the environment; they must never put the key in a URL, prompt, repository, or log. Free accounts receive 15,000 Naming Credits per UTC calendar month. One domain combination costs 1 credit, a public import costs 50, a generated batch of up to 50 costs 500, a ranked batch of up to 30 costs 500, and finalist research costs 250 per finalist. The public health route is the machine-readable source for the current allowance and conversion schedule. ## Core operating rule Use NamingSignal as an evidence-first workflow, not a one-shot name generator. Compile and inspect the brief before generation; correct material product, audience, pain, outcome, mechanism, channel, tone, future-scope, domain, and avoid constraints. Generate a broad field in distinct veins, preserve the ledger, bulk-check domains, check exact namespaces on survivors, and research only one to three finalists. When a founder gives feedback, preserve the approved brief, send liked and disliked examples as preference signals, exclude every prior name, and merge the checked new round into the same project ledger. Treat registry RDAP not-found only as likely unregistered. Timeout, rate limit, unsupported, failed calibration, ambiguity, and missing research remain unknown. Keep hard blockers and active same-category collisions separate from scores. Label deterministic fallback, overall score, and AI editorial rank accurately. Preserve sources, timestamps, evidence state, fallback/usage metadata, feedback rounds, rejections, and manual actions. Require current registrar verification, founder resonance, spoken-name testing when relevant, cultural review, and appropriate legal clearance. NamingSignal never purchases, reserves, files, contacts, or claims legal clearance. ## Choose a surface - CLI: safely inspect local repository context, run deterministic generation/checks, and export decision records. - MCP: orchestrate a read-only 100–200-name sprint from an agent. Prefer the hosted remote endpoint at https://namingsignal.com/mcp; the stdio package is the local alternative. - REST: build a custom workflow from brief, generation, exact checking, ranking, and finalist-research steps. - Web: collaborate with a founder through brief editing, shortlisting, partial-run recovery, research, resonance, and export. ## Recommended sequence 1. Inspect API health/provider readiness when using MCP or REST. 2. Gather bounded primary product context. With the CLI, run brief --dry-run before repository compilation. 3. Compile and approve the editable brief. Do not generate from a visibly broken brief. 4. Generate 100–200 names in distinct veins; retain fallback state and the full ledger when practical. 5. If the founder wants another direction, keep the brief fixed, pass their feedback plus liked/disliked examples, exclude the prior ledger, and merge the checked new round instead of replacing completed work. 6. Check the primary TLD in bulk, then secondary TLDs on survivors. At default REST limits, names multiplied by TLDs must not exceed 150 per request. 7. Check npm, PyPI, GitHub, and Apple exact namespaces on a bounded survivor set. 8. Keep transparent overall score separate from optional AI editorial rank and penalties. 9. Research one to three finalists. Inspect source URLs, semantic collision class, blockers, unknowns, and manual links. 10. Require human registrar, founder-resonance, spoken-name, cultural, and legal review. 11. Export the approved brief, ledger, feedback history, evidence, rejected names/reasons, usage/fallback state, manual actions, and final recommendation. ## Evidence semantics - confirmed: a direct registry or exact namespace response supports a factual state. - inferred: a calibrated absence or source page supports a bounded inference. - unknown: timeout, 429, unsupported, failed calibration, ambiguity, skipped work, conflict, or no proof. - manual: a verification link is supplied because reliable compliant automation is unavailable. Domain status likely_available is a registry signal at check time, not registrar availability, price, purchaseability, or legal clearance. Never turn unknown into available. ## MCP tools - compile_project_brief: compile raw product context into an editable brief. - create_naming_sprint: generate 100–200 names for an initial field or 40 for a feedback round, check selected TLDs, and return survivors; set includeLedger true to retain all checked candidates. For an iteration, pass feedback, likedNames, dislikedNames, and the prior ledger as existingNames. - check_names: run exact domains and optional supported namespaces. - analyze_candidates: research one to three finalists. - get_purchase_links: return manual registrar search links; it never purchases. MCP setup, preferred remote endpoint with no install. Claude Code: claude mcp add --transport http naming-signal https://namingsignal.com/mcp --header "Authorization: Bearer YOUR_NAMINGSIGNAL_KEY". Codex config.toml: [mcp_servers.naming_signal] with url = "https://namingsignal.com/mcp" and bearer_token_env_var = "NAMING_SIGNAL_API_KEY" (plus experimental_use_rmcp_client = true on older Codex versions). Alternative local stdio package: claude mcp add naming-signal --env NAMING_SIGNAL_API_KEY=YOUR_KEY -- npx -y @namingsignal/mcp. MCP create_naming_sprint recompiles raw context and does not currently accept an approved brief object. Its runId is not yet a durable retrieval handle. Use a 360-second tool timeout for large local sprints. ## REST routes - GET https://namingsignal.com/api/v1/health - POST https://namingsignal.com/api/v1/brief - POST https://namingsignal.com/api/v1/generate - POST https://namingsignal.com/api/v1/check - POST https://namingsignal.com/api/v1/rank - POST https://namingsignal.com/api/v1/research - OpenAPI: https://namingsignal.com/openapi.json For POST calls, send Content-Type application/json and a unique Idempotency-Key for each logical body. Keep one X-Name-Ledger-Sprint value across generation, ranking, and research calls in one sprint. Preserve fallback, fallbackReason, modelTrace, usage, quota, sprintBudget, boundedDegradation, cache, and evidence metadata. For an iterative REST generation round, send an iteration object with feedback, likedNames, and dislikedNames. Send every previously generated name in excludedNames. The route uses the feedback as a preference signal, rejects duplicate prior names, and still returns an ordinary candidate batch that must go through the same check and rank steps. ## Complete documentation - Agent workflow: https://github.com/moekoelueker/namingsignal/blob/main/docs/agent-workflow.md - Exact CLI/MCP/API reference: https://namingsignal.com/developers/docs - Open-source MCP and CLI clients: https://github.com/moekoelueker/namingsignal - Privacy: https://namingsignal.com/privacy NamingSignal output is preliminary business research, not legal advice, trademark clearance, a registrar guarantee, or a substitute for qualified review.