#tooldesign

MCP gives you a standard wire format for connecting an agent to tools — it doesn't make the tools on the other end safe to call. Most MCP servers are thin wrappers around an existing REST API, which quietly imports every assumption that API made about having a human developer as its client. Here's what MCP actually is, how it differs from the API you already know, and the specific tool-design mistakes that turn a working MCP server into a flaky agent.

Prompt injection isn't a prompting problem, so you can't prompt your way out of it. It's the same class as SQL injection: data from an untrusted source crosses into a control channel and gets executed as instructions. The web page your agent just fetched, the ticket it just read, the email in its inbox — all of it is attacker-controllable input flowing straight into the one component that can't tell data from commands. Here's the data-flow framing, why 'ignore injected instructions' can't work, and the boundary that actually helps.

Streaming a text response is easy: print tokens as they arrive, order doesn't matter to the reader. Streaming a tool call is not, because the payload is JSON, and partial JSON is not valid JSON. The three ways people handle that mismatch, why two of them break in production, and the pattern that lets you show progress without ever executing on a half-formed argument.

Retrying a read is free. Retrying a write can charge a card twice, send two emails, or book two rooms — and the model has no idea it happened. Retry safety is a property you build into the tool, not a flag you set on the loop. Here's why at-least-once delivery is the default you're actually running, how to derive a stable idempotency key from an agent's intent, and a dedup wrapper that makes any write safe to retry.

A tool schema is a contract with a caller that guesses. This is a concrete walkthrough of the four properties that separate a tool a model uses correctly from one it fumbles: legible schemas, validating boundaries, recoverable errors, and idempotency — with before-and-after code.

Agent tool instructions decide what your agent costs. GitHub kept the same grep/glob/view toolset, rewrote the guidance, and cut review cost by ~20%.

How exposing an internal runtime enum to the model creates a self-reinforcing spawn failure.