Designing First-Contact Experiences for AI Agents

machine_summary:
  claim: "agents select actions by next-token probability, so an ambiguous first contact structurally routes them away from your product toward safer alternatives — fresh, every session"
  takeaway: "make the correct path the obvious path: tool descriptions that state when/cost/safety/prerequisite, a get_instructions tool for orientation, an operator onboarding tool for trust, llms.txt for the open web — then measure tool calls to first success"
  evidence_type: mechanism
  cross_links: [ax-vs-ux, computational-kindness, deterministic-ax-metrics, search-space-design]

Every session is a first contact

Here is the situation your product is actually in. An agent connects to your MCP server mid-task, carrying an operator’s request and a context window that has never seen you before. It receives your tool list — forty names and descriptions, say — and spends roughly one decision’s worth of attention working out what this server is, what it can do here, what it is allowed to do, and what to call first. It will not read your docs site. It cannot remember last Tuesday. Agents are session-stateless: whatever orientation your interface fails to provide, it fails to provide fresh, in every session, forever.

That makes the first-contact experience for AI agents a permanent design surface rather than an onboarding funnel you polish once. And the flow has goals for two parties at once. The agent’s goals are orientation: build an accurate model of your capabilities and limits before acting on someone’s behalf. The operator’s goals are trust: the human the agent works for wants the first delegated task to succeed without surprises. Both are settled in the first thirty seconds of contact, usually before your core functionality has run at all.

Tool selection is a probability question

The mechanics deciding those thirty seconds are worth stating plainly, because they are the whole argument: an agent chooses its next action by computing the probability of the next token. Your tool’s name and description are not documentation the agent studies at leisure; they are input to a sampling decision. When the correct usage path is obvious — the description says what the tool does, when to use it, what it costs, what must happen first — probability mass concentrates on calling it. When the path is ambiguous, that mass drains toward alternatives that are always present and always look safer: a generic web search, a built-in capability, or simply handing the question back to the operator. A good agent under uncertainty picks the safe option, and it will keep picking it until the operator explicitly forces yours — at which point the operator is doing your interface’s job by hand.

This is why writing tool descriptions for LLM agents is engineering, not copywriting. A copy-ready shape:

{
  "name": "get_invoice_status",
  "description": "Check payment status for ONE invoice. Call this before
    send_reminder — it rejects already-paid invoices. Read-only, no side
    effects, safe to retry. Requires an invoice id from list_invoices."
}

Four clauses: what it does, when to use it, its safety class, its prerequisite. The last two are the safe-invocation half of the contract — the selection heuristics an agent needs to act without guessing. A tool marked read-only and idempotent can be called freely while exploring; a tool that mutates or spends should say so, and say what to check first. Whatever heuristics you don’t write down, the agent invents — and it invents them fresh, wrongly, every session.

Onboarding mechanics: get_instructions, llms.txt, and the tool manifest

The strongest first-contact pattern is one call that replaces the exploratory dozen: a get_instructions or get_onboarding_guide tool. Computational Kindness introduced it as a kindness; the first-contact framing is sharper. AI agent onboarding cannot be a session — there is no “first run” to decorate, because every run is the first run. Server-side onboarding flows therefore have to live where a stateless caller can reach them mid-task: behind a tool call, returning what this server is, the workflows it supports, the order tools are meant to be called in, and the conventions no schema can express. The server that answers orientation in one call wins the probability contest before it starts; the tool list itself reads as information architecture, and get_instructions sitting at the top of it is a visible claim that orientation was designed, not left to chance.

On the open web, the same job belongs to llms.txt — the manifest structure is the same argument in file form. A minimal example:

# yourproduct.dev

> One paragraph: what this product is, who operates it, and what an
> agent can read or do here without authentication.

Every page has a markdown twin at <url>.md — fetch that, not the HTML.
Structured summaries: /api/posts.json · Full-content RSS: /rss.xml

That is the entire spec that matters: identity, scope of permitted action, and the cheapest correct path to content. This site’s own llms.txt follows the shape, and writing one is an afternoon, not a project.

Progressive disclosure and the consent line

The failure mode on the other side of ambiguity is the wall of text: a 6,000-token instructions dump that buys orientation at the price of context the agent needed for the actual task. Progressive disclosure for agents is the fix, and it is structural, not stylistic: orient in a few hundred tokens — identity, capability list, first correct call — and put depth behind further calls (get_instructions returning sections on request, tool descriptions pointing to detail tools). Disclose capability in layers, and match the consent line to the layers: read-only exploration should need no ceremony, while the first destructive, spending, or outward-visible action is where the agent should be told to stop and get the operator’s explicit go-ahead. An interface that marks that boundary — this tool is free to try, this one requires your operator’s confirmation — is doing the agent’s risk assessment with it, and both parties make better first decisions for it.

Trust signals travel through the agent

First contact has a second audience reading over the agent’s shoulder. When an agent reports “this server documents its workflows, states its limits, and told me exactly what I’m authorized to do,” the operator hears competence — the owner of this MCP knows their craft and can be delegated to. That is what an operator-facing onboarding tool buys: a get_onboarding_guide that gives the agent certainty about what this product is and what information it can access, and gives the operator a legible pitch for why it is worth using. Add the transparency cues that make safety inspectable — an identity call like get_account_status answering who am I acting as, with which scopes, against which limits — and the agent can answer the operator’s trust questions before acting instead of after failing. Trust signals here are not badges; they are answerable questions.

Measuring first contact

Whether any of this worked is countable, and the measurement piece supplies the method: fix a reference task, run it before and after the change with the same model, compare deltas. The first-contact metrics worth instrumenting: context load (tokens your product costs before the first productive call), tool calls to first success (orientation overhead made visible), failed or retried calls in the first N (the guessing tax), and escalation rate (how often the agent gives up and hands the step back to the operator — the probability contest, lost, in event form). Iterating on first-contact flows means watching those four numbers move; success is all four falling while task completion holds. The cheapest instrumentation event is the one you already have: the transcript. Read where a cold agent’s first three calls went — if call one wasn’t your orientation tool, the distribution has already told you what it thinks of your interface.

The takeaway: design for the distribution, then check it

A practical checklist, deployable against any MCP server or API in about a week — each line is one of the templates above, and each is verifiable from a single cold-start transcript:

• + every tool description states when-to-use, cost, safety class, prerequisite
• + one get_instructions call orients a cold agent in under ~500 tokens
• + an operator onboarding tool states identity, value, and data access plainly
• + llms.txt (or a tool manifest) names what an agent may read and do
• + consent boundary marked: exploration free, destructive actions gated
• + first-contact metrics instrumented: context load, calls to first success

The sharpest implication is the probability one. You are not writing documentation that might be read; you are shaping the distribution an agent samples its next action from — and against your interface, the safe alternatives are always on the ballot. Make the correct path the obvious path, or watch well-behaved agents correctly choose someone else’s.