Tool design and Model Context Protocol

A language model, such as Claude, is software that generates responses from instructions and the information supplied to it. An agent wraps that model in a workflow that can request outside capabilities, and this episode is about making those capabilities useful without quietly giving them too much access. A tool is a named capability the model can request, such as retrieving a complaint summary or proposing a status change, while the trusted application remains responsible for deciding whether the request may actually run. API, which stands for application programming interface, is a defined way for software systems to communicate, but copying an existing API operation into a model tool does not automatically produce a clear or safe design.

A tool contract is the agreement about what one named capability does, what information it accepts and returns, who may use it and what happens when something goes wrong. A schema is a machine-readable description of data structure, such as which fields are required and whether a value must be text, a number, a date, or a group of named fields contained inside another field. Good tool names describe one recognizable operation, because names such as get case and search cases should help the model distinguish retrieving a known record from looking for records that satisfy criteria. A tool description should explain when the operation is appropriate, when it is not, what must already be true, and what the returned data does and does not establish.

Text description

• Prompt guides selection: Tool names, descriptions, and instructions influence the model's probabilistic choice.
• Trusted code validates: The application checks the request and required preconditions.
• Permissions are checked: The application determines whether the caller may perform the operation.
• Execute or refuse: Only trusted code runs the permitted operation or returns a refusal.

A precondition is something that must be true before an operation is valid, such as requiring an open complaint before accepting a proposal to close it. A prompt is text that guides the model's reasoning or behavior, so tool names, descriptions, and system instructions can improve selection but cannot enforce access control. That distinction is fundamental: prompts influence a probabilistic decision, while enforcement is performed by trusted code that validates the request, checks permissions, and either executes or refuses it. Consider Harbour Resolution, a fictional complaints company that will serve as a running example rather than a claim about any real deployment. Its first design exposes one manage case tool with an action field that can read, update, close, delete, pay, or escalate a complaint.

A case worker might see a harmless request for a summary and be tempted to rely on a prompt telling Claude to use only the read action, even though the same available contract also contains destructive and financial actions. The better design separates a broadly available read case summary tool from narrowly controlled tools for materially different changes, because reading, deleting, paying, and escalating do not carry the same consequences. A propose status change tool can record a pending suggestion without altering the complaint, while a separate approval service can require action from a signed-in person with an appropriate organizational role. On the worker's screen, the proposal could show the requested new status, the supporting case facts, and the fact that no change has yet occurred.

Text description

• Conversational confirmation: Shows that someone responded affirmatively in the conversation; it does not establish sufficient authority.
• Authorized approval: A trusted service verifies identity, checks organizational role, and confirms that the current case state permits the action.

The tempting mistake would be to treat the worker saying yes in conversation with Claude as sufficient authority to complete the change. Conversational confirmation merely shows that someone responded affirmatively, whereas authorized approval means a trusted service verified who that person is, checked what role they hold, and confirmed that the current case state permits the action. Keeping approval outside the model's control also preserves the distinction between a model recommending an action and an accountable person or service authorizing it. Narrow tools are not automatically safe, because their implementation can still contain flaws, and splitting a workflow introduces more contracts, state transitions, testing, and interface work.

The benefit is that each permission can be granted separately, each failure has a clearer meaning, and each recorded event can identify the precise operation that was attempted. Telemetry means operational records about what the system did, while an evaluation is a repeatable test of whether the agent selected and used a capability as intended. A single manage case event is difficult to interpret, but separate read, propose, and approve events make monitoring and evaluation more precise without proving that every decision was correct. An input schema should constrain required fields, data types, ranges and groups of fields inside other fields, wherever the interface supports those rules.

Text description

• Check data shape: The schema checks required fields, types, ranges, nested groups, and allowed values.
• Consult current records: The trusted service compares the request with authoritative, current information.
• Check scope and business rules: The service tests authorization, record access, and consistency with the business process.
• Accept or refuse: A request proceeds only if both structural and service-level checks pass.

An enumeration is a closed list of allowed values, so a proposed case status might accept open, pending, or closed rather than arbitrary text. These constraints catch malformed requests, but they establish syntax rather than truth: a value can have the correct shape and still be false, stale, unauthorized, or inconsistent with the business process. At fictional Harbour Resolution, a date can be formatted correctly yet fall before the complaint was created, and a well-formed customer identifier can still refer to a record the caller is forbidden to access. The trusted service behind the tool must therefore repeat validation against current records instead of assuming that schema-valid model output represents a valid business action.

In a separate hypothetical payroll company, an assistant could submit a correctly formatted employee identifier belonging to another customer organization, which is sometimes called another tenant in a shared system. Authentication establishes which person or software client is making a request, while authorization determines what that authenticated identity may do with the specific record or operation. The payroll service should authenticate the caller, derive organizational scope from trusted identity data, and authorize access to the employee record rather than trusting an organization or employee identifier supplied by Claude. This design may require extra identity integration and record lookups, but without them the schema merely confirms that the identifier looks plausible.

Outputs deserve the same care as inputs, because a tool should return only what the next reasoning step needs in stable fields rather than sending an entire record from the underlying service into the information supplied to the model, known as its context. Useful output fields can include stable identifiers, a clear status, the requested facts, explicit missing values, and provenance, which means information about where the returned evidence came from. Evidence is supplied or observed information that may support a conclusion, and its origin and reliability still need to be assessed. Inference is a conclusion drawn from that information, and a careful contract helps the model avoid presenting an inference as something the service directly confirmed.

Text description

• Successful search: no matches: Evidence that the defined search found no matches, subject to its collection, scope, and indexing limits.
• Service unavailable: The search did not establish whether matches exist; a later retry may be appropriate.

For example, a case summary might provide payment status as unknown and identify the billing record that was checked, rather than letting the model infer nonpayment from a missing amount. In a hypothetical legal workplace, an employee could ask an assistant to find matters containing a particular clause and see a concise result on the screen. If the search completed successfully with an empty list of matches, that is evidence that the defined search found no matches, although it does not prove that no relevant material exists outside the searched collection. If the search service instead reports temporarily unavailable, the system has not established whether matches exist, so translating both outcomes into nothing found would create a false conclusion.

The better interface presents no matches and service unavailable as different states, though users must still understand the search scope, indexing delays, and other limits on what a successful result can establish. A normalized error contract is a stable, safe structure that can include an error code, a plain explanation, whether retrying could help, and what correction is required. Missing required evidence is not retryable until someone supplies that evidence, a rate limit means the service is temporarily restricting request frequency and may permit a later retry, and permission denied means rephrasing the same prohibited request should not bypass the refusal. Raw backend exceptions, meaning unfiltered technical error details produced by the underlying service, should not be returned to Claude because they can reveal secrets or internal structure and may contain untrusted text.

Text description

• Model: Reasons over supplied context and requests one of the capabilities made available to it.
• Orchestrator: Manages the workflow, supplies context, exposes selected tools, and decides what follows a request.
• Adapter: Translates between the tool and backend, returns safe normalized errors, and can record restricted diagnostics for authorized operators.
• Backend service: Performs the underlying query or operation subject to trusted validation and permission checks.

An adapter, meaning the trusted component that translates between the model tool and the backend service, can record restricted diagnostic details for authorized operators while returning a safe normalized error to the model. The orchestrator is the application logic that manages the workflow, sends context to the model, exposes selected tools, and decides what happens after a tool request. Automatic tool selection is suitable when Claude may choose whether to use any capability from the permitted set, but permission checks still apply after that choice. Forced selection is useful when the application requires one particular structured operation, such as extracting known fields into an output that conforms to a defined schema, rather than allowing an unconstrained conversational response.

Disabling tools is appropriate during a pure drafting or explanation phase, because a capability that is absent or denied cannot be invoked merely because the model changes its reasoning. In a hypothetical procurement office, a worker drafting a supplier email might see a payment capability beside the writing interface and be tempted to trust an instruction saying not to use it. A safer workflow exposes drafting tools during composition, removes payment capability in that phase, and moves any payment proposal into a separately authorized state where the amount, supplier, and supporting evidence can be reviewed. That stronger boundary adds workflow transitions and may slow urgent work, and those transitions must themselves be tested, but friendly instructions alone cannot substitute for denying an unavailable action.

MCP, which stands for Model Context Protocol, standardizes how an artificial intelligence application can discover and use external context and capabilities. An MCP client requests capabilities from an MCP server, while the server advertises and provides them over a defined connection. The wider application can contain the client alongside other components that manage the user's task. MCP provides common integration patterns rather than a safety guarantee, so every advertised capability still needs deliberate permissions, validation, output limits, and ownership. Within MCP, a tool performs an operation or controlled query and may have a side effect, which means it can change something outside the model, such as creating a pending request.

Text description

• Resource: retrieve context: Exposes addressable content such as a document, schema, log, or record, subject to access checks and data minimization.
• Tool: perform an operation: Runs a controlled query or operation and may cause an external side effect, such as creating a pending request.
• Prompt: reuse guidance: Provides an interaction template that can guide behavior but cannot grant or revoke authority.

A resource exposes addressable context such as a document, schema, log, or record that a client can retrieve, subject to access checks and data minimization, which means returning only the content required for the task. An MCP prompt is a reusable interaction template supported by some clients, and like every other prompt it can guide behavior but cannot grant or revoke authority. A policy manual usually fits naturally as a resource because it is context to retrieve, whereas submitting a case change fits naturally as a tool because it is an operation with consequences. Turning every document into a tool obscures that distinction, although a controlled search tool can reasonably return references to the specific resources that matched its query.

The design goal is semantic fit, meaning that each integration primitive should represent what the capability actually is rather than forcing every need into one shape. A trust boundary is a point where data or control passes between components with different security assumptions, and an MCP server sits on such a boundary just like any other external service. Resource content is still data from across that boundary, so instruction-like text found inside a document should not silently override the orchestrator's rules or acquire permissions of its own. The server should enforce least privilege, meaning each client receives only the capabilities and data access needed for its task, while the server also authenticates the client, authorizes every requested operation, validates inputs against trusted state, limits outputs, protects secrets, and records security-relevant events.

A token is a credential that software presents when requesting access to a service, and a scoped token represents permission limited to particular capabilities or data, which the service must still validate and enforce. An environment variable is a configuration value supplied to a running process, but placing a secret there is appropriate only when the platform's approved secret mechanism protects its storage, delivery, and exposure. For a remote MCP server, transport protection helps defend data against interception or alteration while it is moving, and careful token handling reduces the chance that a credential is leaked or reused outside its intended scope. The server must never accept a model-generated statement such as I am an administrator as proof of identity, because identity comes from the authenticated connection and trusted account data.

Text description

• Progressive discovery: Starts with a manageable set and reveals specialized capabilities when needed; discovery must enforce permissions and constrain results.
• Monolithic context: Places a large collection of tool definitions into every request, consuming context and making similar tools harder to distinguish.

A client may offer convenient direct connections to remote MCP servers with per-server or per-tool settings, but convenience does not remove the need to allowlist, meaning explicitly permit, only the capabilities required for the workflow. Progressive discovery means exposing a manageable initial capability surface and revealing more detailed or specialized tools only when the task genuinely requires them. The alternative is monolithic context, where a large collection of tool definitions and schemas is placed into every model request regardless of relevance. Hundreds of similar definitions can consume the limited context available for reasoning and make tool selection more confusing, while progressive discovery can keep the immediate choices focused.

A secure directory or search capability can reveal a relevant subset, but discovery must itself enforce permissions, constrain results, and produce observable records of what was revealed. Progressive discovery also introduces another dependency and another selection step, so an unavailable or poorly indexed directory can hide a needed tool and a vague query can surface the wrong subset. A shell is a general command interface to the operating system, text search looks inside files for matching content, and file-pattern matching locates paths whose names fit a pattern. In Claude Code, common capabilities include Read for inspecting files, Write and Edit for changing them, Bash for issuing shell commands, Grep for searching text, and Glob for matching file paths by patterns.

A code-explanation agent may need only reading, text search, and file matching, because adding editing or shell access would provide power unrelated to explaining the existing code. A remediation agent may legitimately need editing and test execution, but its access should still be confined to the intended code repository, meaning the managed collection of project files, and to commands required by the task. Shell access is especially sensitive because one general interface may reach files, networks, running processes, credentials and destructive commands. It can also reach tools that install or update software and its required components, so a convenient command interface can carry much broader power than the task needs.

Text description

• Sandboxing: Confines execution to an isolated environment.
• Command policy: Restricts which commands or targets are permitted.
• Approvals: Introduce accountable human decisions for sensitive actions.
• Environment isolation: Limits which credentials and external systems the process can reach.

Sandboxing confines execution to an isolated environment, command policy restricts which commands or targets are permitted, approvals introduce accountable human decisions, and environment isolation limits what credentials and systems the process can reach. In a hypothetical software team, a reviewer who only wants an explanation might be tempted to enable the shell for convenience, while the better design offers read and search capabilities and reserves test commands for a later remediation phase. The reviewer would see fewer available actions and clearer read-only behavior, although even read access must exclude unrelated repositories and secret files and cannot guarantee that retrieved code is trustworthy. Every capability should have an accountable owner who defines its purpose, permission boundary, validation rules, output contract, failure behavior, monitoring, and retirement path.

The durable synthesis is simple: give the model clear descriptions for reasoning, give trusted services narrow authority for enforcement, preserve the differences between syntax and truth, authentication and authorization, evidence and inference, and confirmation and approved action, and expect every boundary to have limitations rather than promising absolute safety.