Socratic APIs: The Skill-Free Agent Architecture

The skill-free agent architecture behind TAP.

At human.tech, we've spent a lot of time thinking about how agents actually interact with the world. For a long time, the industry has relied on MCP servers or "skills," essentially feeding the agent markdown or upfront documentation to explain how a tool works.

The problem is that this approach is fundamentally flawed. MCP is brittle and requires a custom server to be built and maintained for every single service. Skills cause context bloat; loading documentation into the context window for every tool degrades the instruction-following capabilities of small models.

We decided to stop relying on either. To do that, we built Socratic APIs.

What are Socratic APIs?

Socratic APIs are the core technical mechanism underlying TAP's (Tool Authorization Protocol) skill-free architecture. Instead of requiring upfront documentation or new code for every service, Socratic APIs teach agents how to use them through the interaction itself, in real time.

Internally, we describe it simply: "TAP = 'Socratic API,' no new code/context per tool."

By pairing Socratic APIs with policy-based credential isolation, we've removed the need for the traditional "manual" provided to the agent. The agent learns the tool as it interacts with it.

In practice it comes down to two things: one route that tells an agent enough to get started, and errors that tell it exactly what to do next.

As an example, here is TAP's entry point:

# TAP — Tool Authorization Proxy
Proxy: https://proxy.tap.human.tech

Credential proxy for AI agents. Agents forward API calls; TAP injects credentials.

## Quick start

1. GET https://proxy.tap.human.tech/agent/services  (header: X-TAP-Key)
   — discover credentials and usage templates
2. POST https://proxy.tap.human.tech/forward — send authenticated upstream call

The other half is the errors. When you make an invalid request, TAP doesn't return a 400 saying "invalid request". Instead:

{
  "error": "Unknown header: x-tap-body",
  "detail": "Recognized X-TAP-* headers: X-TAP-Key, X-TAP-Credential,
             X-TAP-Target, X-TAP-Method, X-TAP-End-User, X-TAP-Auth-Mode.
             Other headers pass through to the upstream unchanged.
             Request bodies go in the HTTP body."
}

And if you ask for a credential that isn't there, the error makes a suggestion

{
  "error": "Credential 'stripe-prod' is not allowed for any provided key",
  "fix": "Call GET /agent/services to see which credentials are available.
          If using multiple keys, ensure the key that owns this credential
          is included in X-TAP-Key.",
  "services_url": "/agent/services"
}

Why this matters

The shift to a Socratic approach solves two primary blockers.

1. Context is paid on demand, not upfront

The tempting claim is that this eliminates context cost. But that is actually not true. The real numbers are more interesting.

/instructions is about 4 KB. The skill file it replaced was about 4.5 KB. On size alone, it's a wash. But the size of the entry document is not the most important size in terms of performance.

The discovery route was surprisingly large: on an account with 48 credentials connected, /agent/services returns about 165 KB, which is roughly 3.3 KB per credential.

The important part isn't context size; it's when agents load the context. MCP tool definitions sit in context for the whole session whether or not you touch that service, whereas a skill has to be loaded before it can help. The Socratic version costs nothing until the agent needs to discover something, costing in proportion to what you actually have connected rather than everything that exists.

2. Small model enablement

Small models often fail when faced with complex MCP tool schemas or dense skills documentation. A Socratic API hands them one short instruction at a time and corrects them in place when they get it wrong. This lets them reach tools they would otherwise use incorrectly.

We ran this against cheaper models and it held up where skills didn't. This is an observation from use, not a measured result, as we haven't benchmarked it properly yet. That benchmark is the next thing we intend to publish.

MCP is the transport, not the catalog

If you've connected to TAP recently you'll have noticed we ship an MCP server. mcp.tap.human.tech connects Claude, ChatGPT, and anything else that speaks MCP but can't make raw HTTP calls. That looks like a contradiction. But the key difference is that MCP is solely used as a transport here, not as a catalog.

The MCP server exposes two tools. tap_discover lists what this connection can reach. tap_call calls any API by credential name. When something's missing or denied, the tool result carries the same corrective hint the HTTP error would. It's the Socratic contract spoken over a different wire, and it means you connect once instead of installing a Gmail server, a Stripe server, and a GitHub server.

How to make your own API Socratic

Four rules, which is most of what this is:

1. One bootstrap route. An agent hits this with no prior knowledge and learns enough to make the second call. Keep it small enough to read, and no larger.
2. Point, don't enumerate. If a route can tell the agent something, don't preload it. The bootstrap doc names the discovery route, and the discovery route holds the detail.
3. Errors carry the repair, not the diagnosis. "Invalid credential" is a diagnosis. "Call /agent/services to see what's available" is a repair. Failures should have instructions for the next action.
4. Never let the agent keep a copy. The moment your docs live on the client, they can go stale. A stale doc that an agent trusts is almost worse than no doc at all.

A simpler way to build

By moving away from the "documentation-first" model, we've reached a point where adding a new tool or service requires no new code. We no longer have to maintain a library of brittle servers or manage an ever-growing list of markdown files just to get an agent to perform a basic task.

Socratic APIs let us keep our agents lean, our context windows honest, and our integrations scalable.

TAP is available at tap.human.tech. The story of why we built it is in Announcing TAP.