The quality of an MCP integration often depends less on the transport than on the contract of each tool. Claude sees a name, description, input schema, and eventually a result. From that limited interface it must decide whether the tool is appropriate, construct valid arguments, interpret the outcome, and determine the next step. In Claude Engineering, a tool contract should be designed like a typed API for an intelligent caller: precise enough to constrain mistakes, descriptive enough to guide selection, and narrow enough that one valid call cannot create unintended authority.
Current Claude tool definitions use JSON Schema for tool inputs, and Anthropic supports strict tool use so generated arguments conform to the declared schema. MCP SDKs likewise validate tool inputs and can support structured output schemas. Schema validity is only the first layer. A technically valid object can still express the wrong business action, so names, descriptions, enums, identifiers, idempotency, result semantics, and error behavior all belong in the contract.
Give each tool one clear business purpose
A tool should answer one question or perform one coherent action. Avoid broad tools such as manage_customer that can search, edit, delete, and message depending on optional parameters. Separate capabilities make selection easier and permissions safer because the effect of a call is visible from the tool name itself.
Agent tool reasoning becomes more reliable when the model chooses among semantically distinct operations. The backend can also apply different approval, audit, and rate-limit policies to reads and writes without parsing a generic command object.
Write descriptions that explain when to use the tool and when not to
The description is part of the model’s routing logic. State the capability, important preconditions, and exclusions. If a tool searches only active orders, say so. If a tool sends an external message immediately, say that it has a side effect. If another tool should be used for historical data, mention the distinction.
Descriptions should not become mini prompt documents full of policy that the executor ought to enforce. API security requires server-side checks even when the description tells Claude what is allowed. Documentation guides the caller; enforcement protects the system.
Use the narrowest JSON Schema that represents valid requests
Prefer typed fields, required properties, enums, bounded numbers, and explicit arrays over one free-form string. If an action supports only three deployment environments, use an enum rather than asking Claude to invent a name. If a field is required to execute safely, make it required rather than hoping the model includes it.
Anthropic’s agent security boundary improves when the schema removes impossible or dangerous combinations before execution. Strict tool use can guarantee schema conformance, but the schema itself must encode the right constraints. A permissive schema can be strictly followed and still be unsafe.
Prefer stable identifiers over ambiguous human-readable names
Names collide, change, and can be misspelled. When a tool acts on an existing resource, prefer stable IDs selected from a prior lookup result. The lookup can return both an ID and a display label, allowing Claude to reason with understandable text while the executor receives an unambiguous reference.
This is especially important for consequential actions. Approval boundaries are clearer when the confirmation shows the display name but the transaction is bound to the immutable ID. That prevents a later rename from redirecting an approved action.
Make side effects and idempotency explicit in the contract
A caller should know whether the tool is read-only, creates a resource, updates one, sends something externally, or deletes data. For operations that might be retried, include an idempotency key or request identifier when the backend supports it. The executor should return the original result if the same request is safely replayed.
Agent lifecycle management needs this because retries can come from network failures, orchestration recovery, or model replanning. A tool contract that makes duplicate side effects impossible is more robust than a prompt that merely tells Claude “do not call twice.”
Return structured outputs that distinguish result, status, and evidence
Tool results should have predictable fields such as status, resource ID, user-facing summary, warnings, and relevant data. If the result is too large, return a reference to a resource instead of embedding thousands of records. Structured outputs make it easier for Claude to continue reasoning without parsing fragile prose.
GenAI observability also benefits from stable result fields because logs can capture operation IDs and error classes without recording sensitive payloads. The result contract should help both the model and the operator understand what happened.
Design errors as part of the normal contract
Do not reduce every failure to “tool failed.” Distinguish invalid input, unauthorized access, missing resources, conflicts, rate limits, transient downstream failures, and permanent business-rule rejections. Include machine-readable error codes plus concise human-readable detail. State whether retry might succeed when that can be known safely.
Claude can then choose a better next step: ask the user for missing information, select another resource, wait and retry, or stop. Reliable AI systems are built from predictable failure behavior, not only successful calls.
Keep secrets and privileged context out of schemas and result payloads
A tool schema is visible to the model and may be cached or logged by supporting infrastructure. Do not put secrets, protected health information, private tokens, or sensitive constants into property names, enum values, examples, or descriptions. Pass sensitive values through the executor’s credential system rather than asking Claude to supply them.
Identity architecture should decide which credential the executor uses for the action. The tool call should express intent and resource scope, not carry raw authority. This separation is especially important for remote MCP servers shared by multiple users or agents.
Version contracts through additive change before breaking change
Tool contracts evolve. Add optional fields before making them required, keep stable output fields when possible, and introduce a new tool name for materially different behavior rather than silently changing semantics. Contract tests should cover representative calls, validation failures, permission checks, and result shapes.
Anthropic and MCP give models a standardized way to call tools, but reliability comes from disciplined contracts. Clear purpose, precise descriptions, constrained schemas, stable identifiers, explicit side effects, structured results, typed errors, and secure credential handling make the agent easier to trust. The best tool contract is one where both Claude and a human reviewer can predict what a valid call means before it runs.
Optional parameters deserve careful review because they are a common source of ambiguity. A field should be optional only when the server has a safe, deterministic default. If omitting a destination, environment, or scope could cause the backend to guess, make the field required or split the operation into separate tools. Hidden defaults are convenient for human SDK users but can be dangerous for model-driven execution.
Units and formats should be explicit. Use ISO timestamps, currency codes, normalized time zones, bounded integers, and documented enum values rather than strings such as “tomorrow morning” or “about five hundred.” If the application accepts natural language, normalize it in a separate interpretation step and show the resolved value before a consequential call. Tool contracts are strongest when execution parameters are unambiguous at the boundary.
Schema changes should be tested against real model behavior, not only conventional clients. A new optional field or renamed description can alter which tool Claude selects even when every old request remains valid. Keep representative agent conversations in regression tests and compare tool-selection accuracy before deploying contract changes. Model-facing APIs have a semantic compatibility surface in addition to a syntactic one.
Use examples carefully. A concise example can clarify a complex field, but examples can also bias the model toward one value or pattern. Prefer descriptions and enums that encode the real domain. When examples are necessary, vary them across tests so the agent learns the contract rather than merely copying a sample. The contract should remain understandable when the example is removed.
Authorization-relevant fields should be independently validated even when strict schema validation passes. A schema can prove that account_id is a string; it cannot prove that the caller may act on that account. The executor should derive allowed scope from identity and compare the requested resource against it. This keeps the tool contract expressive without turning model-supplied parameters into authorization claims.
Result schemas should be stable enough for multi-step reasoning. If one tool returns customerId and another expects customer_id, Claude may bridge the difference, but every translation is another opportunity for error. Shared identifier conventions, timestamp formats, and status enums reduce cognitive load across the toolset. A coherent contract family often improves agent reliability more than adding another paragraph to individual tool descriptions.
Finally, measure contract quality in production. Track validation failures, tool-selection corrections, retries caused by ambiguous errors, and calls that users later undo. Those signals reveal where the schema or description is confusing the model. Contract design should improve from observed failures just like any other API: the goal is not a theoretically elegant schema, but one that produces safe and predictable behavior across real conversations.
Small contracts are easier to secure.
