Tool use and MCP

MCP tool design: study the contract, not just the call.

Reliable agents do not need the most tools. They need well-scoped tools with clear inputs, bounded authority, observable outcomes, and a safe recovery path when the world does not behave as expected.

What MCP changes—and what it does not

Model Context Protocol standardizes a way for applications to expose context and capabilities to models. That standard interface does not make every connected server trustworthy, every action safe, or every response correct. Architecture still starts with the boundary: which system owns the data, what authority is delegated, and how a human can audit the result.

When evaluating a scenario, ask whether the proposed tool exposes only what is necessary. A narrow operation with constrained parameters is generally easier to secure, test, observe, and recover from than a broad “do everything” integration.

The four tool-design decisions

One clear purpose

A tool should solve one understandable task. Combining read, write, approval, and payment behavior behind a vague name makes it harder for both people and agents to reason about risk.

A strict input contract

Define the parameters the tool accepts, validate them at the boundary, and return errors that help the caller recover without guessing.

Explicit side effects

Separate lookup actions from actions that modify data or communicate externally. Require deliberate approval where an action can be costly, irreversible, or security-sensitive.

Recoverable execution

Plan for timeouts, duplicate calls, partial completion, and stale data. Idempotent operations and useful status responses make recovery possible.

A quick scenario-review loop

  1. Identify the user goal and the action that would satisfy it.
  2. Mark the trust boundary: untrusted input, sensitive data, external system, or irreversible action.
  3. Choose the smallest tool contract that can make progress safely.
  4. Decide what evidence proves success and what condition triggers a retry, escalation, or human review.

This loop is more robust than simply asking whether a tool can perform an action. It tests whether the workflow remains correct when the request is ambiguous, the tool fails, or the returned data should not be trusted blindly.

Primary sources to check

Use the system design checklist

Review tool purpose, inputs, authority, side effects, and recovery before connecting a workflow to an external system.

Open the Claude system design checklist →

Practise the architecture decision.

Use original tool-use scenarios to distinguish a technically possible call from a safe, observable system design.

Practise tool-use questions →