Making Your API Agent-Friendly: What I Learned the Hard Way

05 Apr 2026

If you run a service with a REST API and you want agents to use it, the path forward is not obvious. I spent a lot of time figuring it out with HealthExport, a service I’ve been running for seven years. Here’s what I learned.

The Problem Worth Solving

Agents are becoming real users. They can call APIs, run tools, and compose multi-step workflows. A REST API gets you there, but the gap between usable and genuinely useful is worth closing. That’s what I set out to do with HealthExport, a service I’ve been running for seven years. Here’s what I learned.

Start with the CLI

My first move was building a Go CLI in the style of GitHub’s gh tool. Single binary, Homebrew distribution, clean stdout/stderr separation, predictable exit codes, JSON output mode. The kind of thing you’d build for a technically-minded human user.

What I didn’t expect: this also made the tool immediately usable by coding agents. Drop the GitHub repository URL into Claude Code or Codex, and it reads the README, installs the tool via Homebrew, and starts using it. No special integration needed. A well-documented CLI is already agent-friendly.

I also set up an automated release pipeline: push a tag, GitHub Actions builds the binaries, attaches them to the release, and updates the Homebrew tap automatically. Agents helped me set this up, and it has run without issues since. Worth doing once.

The VM Wall and the MCP Gateway

The CLI worked great from a local terminal and from coding agents. Then I wanted to use it from Claude Cowork.

Cowork runs in a Linux virtual machine. It doesn’t have access to your local environment, your installed binaries, or your filesystem. The CLI simply doesn’t exist from Cowork’s perspective.

The solution was to build a local MCP server that acts as a gateway between Cowork and the CLI running on the host machine. Packaged as a plugin users install into Cowork, it translates tool calls into CLI calls on the host and returns the result. The privacy model stays intact — decryption still happens locally, the raw account key never leaves the machine. And Cowork gets access to the same capabilities the CLI provides.

The Missing Piece

Here’s the part nobody writes about.

Even with the plugin installed and configured, Cowork sometimes just didn’t use it. The tool appeared in the list but got marked as deferred, and the agent would proceed without invoking it. I spent a lot of time tweaking tool names, descriptions, and titles. It helped a little, but not reliably.

The solution turned out to be a skill file. The release bundle — the same GitHub release that distributes the plugin — also includes a skill. The skill does one thing: it tells the agent that when a user asks about health or fitness data, it should look for this specific connection, even if it appears in deferred tools.

After adding the skill, the reliability improved dramatically. The agent now consistently reaches for the tool when it should.

The lesson: discoverability is a separate problem from capability. You can build a perfect integration and still have agents ignore it because they don’t know when to reach for it. Solving that explicitly, with a skill or equivalent hint, is not optional.

Takeaways

• A well-built CLI is already agent-friendly. Coding agents can discover, install, and use it from a README alone.
• MCP gateways bridge the VM gap, but they introduce a new class of problem.
• Discoverability is not automatic. If your tool can be deferred, it will be. Provide explicit guidance on when to use it.