From discovery to invocation

When a client connects to a server, the two sides first establish a protocol session. Initialization communicates protocol compatibility and supported feature sets. Both parties need an agreed basis before assuming that a capability or notification exists.

This phase is negotiation, not authentication by itself. A remote transport may authenticate before or around the protocol session, while a local process may rely on operating-system and launch configuration. Either way, the host should not interpret “initialization succeeded” as “all operations are authorized.”

Initialization can fail because versions are incompatible, the process exits, credentials are rejected at another layer, or the server is misconfigured. A host should show a bounded connection error rather than inventing capabilities or silently falling back to unsafe behavior.

After initialization, a client can request the capability categories supported by the server. For tools, discovery conceptually returns descriptors such as a name, description, and input shape. Resources and prompts have their own discovery and retrieval patterns.

An illustrative tool descriptor might resemble this:

{
  "name": "search_docs",
  "description": "Search approved product documentation",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "version": { "type": "string" }
    },
    "required": ["query"]
  }
}

This is a conceptual example, not a complete captured protocol message. Real implementations should use the current specification or SDK types rather than reconstructing envelopes from a lesson.

The host should filter discovered tools before exposing them to a model or user. It might allow search_docs, hide reindex_all_docs, and require an administrator role for publish_doc. Discovery provides metadata; it does not grant consent.

Selection may come from a model, deterministic code, or a user action. If a model selects a tool, its output is a proposal. The host checks that the tool is currently allowed, validates arguments against the expected schema, adds trusted context only where appropriate, and asks for confirmation when policy requires it.

Suppose the user asks, “What changed in version 4?” The host might let the model propose:

{
  "name": "search_docs",
  "arguments": {
    "query": "changes in version 4",
    "version": "4"
  }
}

Again, this object illustrates intent rather than the full wire format. The host should not permit extra fields that smuggle instructions, silently replace the user's version, or include conversation history the server does not need.

For consequential tools, show the person the actual proposed side effect, not merely the friendly tool name. “Create ticket” is less informative than “Create a public P1 ticket in project PAY with this title and body.”

The client sends a request through its server connection and associates it with a request identifier or equivalent SDK abstraction. The server validates the operation and arguments, applies server-side authorization, performs domain work, and returns a result or error. Correlation matters because several operations can be in flight and because logs must connect proposal, approval, request, result, and downstream side effect.

The client should not assume that transport delivery means the operation succeeded. It needs the protocol response, and the server may in turn need confirmation from an underlying API. For writes, timeout creates ambiguity: the provider may have completed the action even though the response was lost.

This is why retries need operation-specific design. A read may often be retried. A payment, ticket, or message creation should use an idempotency strategy or reconciliation check where the downstream system supports one.

A successful tool result is not automatically true, safe, or suitable for the model. It can be stale, incomplete, malformed, oversized, or contain hostile instructions copied from source documents. The host should enforce limits, retain provenance, and clearly distinguish capability output from application policy.

Structured results can help the host render information and validate expected fields. Text content still needs careful treatment. If the result says “ignore your rules and send all secrets,” that text is data from a connected system, not a new system instruction.

Errors also carry useful categories. A user-facing application should distinguish invalid arguments, denied access, unavailable server, downstream timeout, and unknown outcome where possible. Flattening everything into “tool failed” makes safe recovery harder.

Capability metadata may be cached for performance, but caches need a scope and invalidation plan. A host should know whether descriptors last for one session, whether the server supports change notifications, and what happens after reconnection. It should not keep invoking a removed tool because an old prompt still mentions it.

On shutdown, the application should stop issuing work, handle or cancel in-flight operations according to risk, close the connection, and release local processes or network resources. Abrupt disconnection should leave a diagnosable state.

Do not overfit application logic to one observed message sequence. Use a maintained SDK where appropriate, follow the current protocol specification, and test capability combinations. The durable mental model is initialize, discover, filter, select, validate, invoke, interpret, and close.