{
  "$schema": "https://agentsfirst.dev/schemas/glossary.v0.json",
  "framework": "Agents First",
  "version": "0.7",
  "framework_url": "https://agentsfirst.dev",
  "glossary_url": "https://agentsfirst.dev/glossary/",
  "updated": "2026-05-10",
  "anti_patterns": [
    {
      "slug": "lazy-wrapper",
      "name": "The Lazy Wrapper",
      "definition": "The agent interface is fetch() with a different name. No domain knowledge, no validation, no structured errors — the agent asks for active deals and gets back 47KB of nested JSON, undocumented field names, and three timestamp formats. Handing someone the raw database and calling it a product.",
      "url": "https://agentsfirst.dev/glossary/#lazy-wrapper",
      "opposes_principle": "interface-first"
    },
    {
      "slug": "invisible-product",
      "name": "The Invisible Product",
      "definition": "Web app exists. Maybe an API later. Agent interface never. The product is invisible to the agent ecosystem — when an agent goes looking, it doesn't find you.",
      "url": "https://agentsfirst.dev/glossary/#invisible-product",
      "opposes_principle": "interface-first"
    },
    {
      "slug": "agents-without-rules",
      "name": "Agents Without Rules",
      "definition": "Tools exist; AGENTS.md does not. The agent hallucinates identifiers, blows past rate limits, creates duplicates, sends emails to the wrong people. Then someone declares 'AI doesn't work' and turns it off.",
      "url": "https://agentsfirst.dev/glossary/#agents-without-rules",
      "opposes_principle": "contract-first"
    },
    {
      "slug": "single-model-trust",
      "name": "Single-Model Trust",
      "definition": "Acting on one LLM's recommendation for decisions that cost money or affect users. One model says 'this code is safe to deploy.' Is it? You have no idea. A coin flip dressed up as confidence.",
      "url": "https://agentsfirst.dev/glossary/#single-model-trust",
      "opposes_principle": "multi-model-verification"
    },
    {
      "slug": "slow-chatbot",
      "name": "The Slow Chatbot",
      "definition": "Every agent action requires explicit human approval. If the agent can't do anything without asking permission, it's not an agent — it's a chatbot with extra steps.",
      "url": "https://agentsfirst.dev/glossary/#slow-chatbot",
      "opposes_principle": "autonomous-recovery"
    },
    {
      "slug": "ship-and-forget",
      "name": "Ship and Forget",
      "definition": "Launch an agent integration for the press release. Don't maintain it. Don't test it. Let it rot. Worse than no integration, because now agents try to use the product, fail, and learn to avoid it.",
      "url": "https://agentsfirst.dev/glossary/#ship-and-forget",
      "opposes_principle": "prep-gates"
    },
    {
      "slug": "god-server",
      "name": "The God Server",
      "definition": "An agent interface that exposes 200 tools because it wraps an entire platform. Agents choke on tool selection when there are too many options. Ten well-chosen tools beat two hundred exhaustive ones.",
      "url": "https://agentsfirst.dev/glossary/#god-server",
      "opposes_principle": "interface-first"
    },
    {
      "slug": "black-box-server",
      "name": "The Black Box Server",
      "definition": "An agent server with no introspection tool. The only way to ask 'what is the state of the work?' is to shell into the database or scrape application logs. Operator agents go blind, and the dashboard you didn't build gets built by every consumer rolling its own.",
      "url": "https://agentsfirst.dev/glossary/#black-box-server",
      "opposes_principle": "inspectable-state"
    }
  ],
  "principles": [
    {
      "slug": "interface-first",
      "name": "Interface First",
      "definition": "Design the agent interface — MCP tools, CLI commands, typed SDK signatures — before any human UI. The tool definitions are the first artifact of any feature, regardless of protocol.",
      "url": "https://agentsfirst.dev/glossary/#interface-first",
      "deep_dive": "https://agentsfirst.dev/principles/interface-first/"
    },
    {
      "slug": "contract-first",
      "name": "Contract First",
      "definition": "Write usage rules — permissions, constraints, sequences, formatting — before implementation. The canonical place these live is a project's AGENTS.md.",
      "url": "https://agentsfirst.dev/glossary/#contract-first",
      "deep_dive": "https://agentsfirst.dev/principles/contract-first/"
    },
    {
      "slug": "prep-gates",
      "name": "Prep Gates",
      "definition": "Pre-flight checks — credentials valid, IDs fresh, system healthy — before every agent session. Stale context is the #1 source of agent errors.",
      "url": "https://agentsfirst.dev/glossary/#prep-gates",
      "deep_dive": "https://agentsfirst.dev/principles/prep-gates/"
    },
    {
      "slug": "typed-state",
      "name": "Typed State",
      "definition": "All persistent agent state flows through a single structured data contract with versioned migrations. Each module owns its slice.",
      "url": "https://agentsfirst.dev/glossary/#typed-state",
      "deep_dive": "https://agentsfirst.dev/principles/typed-state/"
    },
    {
      "slug": "visible-outputs",
      "name": "Visible Outputs",
      "definition": "Agent actions produce human-readable results in existing workflow tools — Slack, email, task manager — not a JSON blob in a dashboard nobody opens.",
      "url": "https://agentsfirst.dev/glossary/#visible-outputs",
      "deep_dive": "https://agentsfirst.dev/principles/visible-outputs/"
    },
    {
      "slug": "multi-model-verification",
      "name": "Multi-Model Verification",
      "definition": "High-stakes decisions fan out to multiple models. Trust agreement. A finding three models flag is almost certainly real.",
      "url": "https://agentsfirst.dev/glossary/#multi-model-verification",
      "deep_dive": "https://agentsfirst.dev/principles/multi-model-verification/"
    },
    {
      "slug": "perspective-dispatch",
      "name": "Perspective Dispatch",
      "definition": "Complex reviews dispatch multiple constrained perspectives (security, UX, new-user, performance) against the same artifact. Each persona has a defined focus area; findings outside it are discarded.",
      "url": "https://agentsfirst.dev/glossary/#perspective-dispatch",
      "deep_dive": "https://agentsfirst.dev/principles/perspective-dispatch/"
    },
    {
      "slug": "autonomous-recovery",
      "name": "Autonomous Recovery",
      "definition": "The system retries with backoff before alerting. Humans only get pulled in when self-healing has already failed — and the alert includes what happened, what was tried, and a direct link to take manual action.",
      "url": "https://agentsfirst.dev/glossary/#autonomous-recovery",
      "deep_dive": "https://agentsfirst.dev/principles/autonomous-recovery/"
    },
    {
      "slug": "inspectable-state",
      "name": "Inspectable State",
      "definition": "Every agent server exposes its own operational state — queue depth, throughput, recent activity, trends, health — via a typed agent tool, not just a human dashboard. The complement to Visible Outputs. Where Prep Gates answers 'is the system READY?', Inspectable State answers 'what is the STATE of the work?'.",
      "url": "https://agentsfirst.dev/glossary/#inspectable-state",
      "deep_dive": "https://agentsfirst.dev/principles/inspectable-state/"
    }
  ],
  "concepts": [
    {
      "slug": "mcp",
      "name": "MCP (Model Context Protocol)",
      "definition": "Anthropic's open spec for connecting AI agents to external tools. Self-describing tool definitions, automatic discovery on connect. Adopted by Anthropic, OpenAI, Google, Microsoft. 110M+ monthly downloads as of 2026.",
      "url": "https://agentsfirst.dev/glossary/#mcp"
    },
    {
      "slug": "code-mode",
      "name": "Code Mode",
      "definition": "Cloudflare's pattern of replacing tool definitions with a typed SDK in a sandbox. The agent writes code against the SDK instead of calling tools one at a time. Reduced tool context from 1.17M tokens to ~1,000 tokens — a 99.9% reduction.",
      "url": "https://agentsfirst.dev/glossary/#code-mode"
    },
    {
      "slug": "agents-md",
      "name": "AGENTS.md",
      "definition": "Repository file containing usage rules for AI agents. The canonical place a Contract First lives. Sections typically include permissions, sequence, identifiers, errors, anti-patterns to avoid.",
      "url": "https://agentsfirst.dev/glossary/#agents-md"
    },
    {
      "slug": "two-customers",
      "name": "Two Customers",
      "definition": "The framing at the heart of Agents First: every product now has two customers — the human who pays, and the agent who decides. The human reads marketing pages and signs contracts; the agent picks from the tool list available to it.",
      "url": "https://agentsfirst.dev/glossary/#two-customers"
    },
    {
      "slug": "adoption-levels",
      "name": "Adoption Levels",
      "definition": "The 0–4 scale for how seriously a product treats agents. 0: No agent access. 1: Afterthought. 2: Agent-Aware. 3: Agents First. 4: Agent-Driven. Most companies are at 0 or 1; the opportunity is at 3.",
      "url": "https://agentsfirst.dev/glossary/#adoption-levels"
    },
    {
      "slug": "progressive-discovery",
      "name": "Progressive Discovery",
      "definition": "Pattern of letting the agent search/fetch tool definitions on demand instead of front-loading all of them into context. Anthropic's approach reduces tool context by 98.7%.",
      "url": "https://agentsfirst.dev/glossary/#progressive-discovery"
    },
    {
      "slug": "scoped-tokens",
      "name": "Scoped Tokens",
      "definition": "Auth tokens limited to the minimum permissions needed. Default for agent connections. Read-only token doesn't allow writes; per-project token doesn't unlock other projects.",
      "url": "https://agentsfirst.dev/glossary/#scoped-tokens"
    },
    {
      "slug": "oauth-pkce",
      "name": "OAuth 2.0 with PKCE",
      "definition": "Recommended user-facing auth flow for agent tools. The user authenticates, grants scoped permissions, gets a token that can be revoked independently.",
      "url": "https://agentsfirst.dev/glossary/#oauth-pkce"
    },
    {
      "slug": "smallest-experiment",
      "name": "Smallest Experiment",
      "definition": "Minimum viable Agents First adoption: pick the single most-used operation in your product, wrap it as one verb-first agent tool with typed parameters and structured errors, ship it, measure time to first agent action and tool success rate.",
      "url": "https://agentsfirst.dev/glossary/#smallest-experiment"
    }
  ],
  "metrics": [
    {
      "slug": "time-to-first-agent-action",
      "name": "Time to First Agent Action",
      "definition": "Latency from tool installation to the first successful tool call. Target: under 60 seconds.",
      "url": "https://agentsfirst.dev/glossary/#time-to-first-agent-action"
    },
    {
      "slug": "agent-activation-rate",
      "name": "Agent Activation Rate",
      "definition": "Percentage of installations that result in at least one tool call within 7 days.",
      "url": "https://agentsfirst.dev/glossary/#agent-activation-rate"
    },
    {
      "slug": "agent-return-rate",
      "name": "Agent Return Rate",
      "definition": "How often agents call your tools after the first session — the agent-side equivalent of D7/D30 retention.",
      "url": "https://agentsfirst.dev/glossary/#agent-return-rate"
    },
    {
      "slug": "tool-success-rate",
      "name": "Tool Success Rate",
      "definition": "Percentage of tool calls that succeed without retries or human escalation. Below 90% means tool design needs work.",
      "url": "https://agentsfirst.dev/glossary/#tool-success-rate"
    },
    {
      "slug": "tool-selection-accuracy",
      "name": "Tool Selection Accuracy",
      "definition": "When multiple tools are available, how often the agent picks the right one on the first try. Low accuracy means tool names or descriptions are ambiguous.",
      "url": "https://agentsfirst.dev/glossary/#tool-selection-accuracy"
    },
    {
      "slug": "human-visibility-rate",
      "name": "Human Visibility Rate",
      "definition": "Percentage of agent actions that produce a human-visible artifact within 24 hours. If agents are using your product and humans don't know, you have an attribution problem.",
      "url": "https://agentsfirst.dev/glossary/#human-visibility-rate"
    },
    {
      "slug": "agent-to-human-conversion",
      "name": "Agent-to-Human Conversion",
      "definition": "For products with free tiers, how often agent usage drives a human signup or upgrade.",
      "url": "https://agentsfirst.dev/glossary/#agent-to-human-conversion"
    }
  ]
}