A tool is a controlled application boundary
The Model Context Protocol tools specification describes named tools with input schemas and optional output schemas. It also discusses visible tool activity and human control. These are useful interface ideas even when an application does not use MCP.
A model's tool call is a proposed operation. The host application still needs to validate the arguments, establish the user's authority, and decide whether execution is allowed. A descriptive tool name is not an authorization mechanism.
Technical foundation: Model Context Protocol: Tools, specification 2025-06-18
Prefer precise operations
A tool called manage_shop tells the model very little about acceptable behavior. More precise operations such as search_products, read_order, and prepare_delivery describe different jobs and permissions. Keep read operations separate from writes so the application can apply different controls.
Describe arguments in business terms. An order identifier should mean a specific identifier format, not any text that resembles an order. Set bounds on page size and date ranges. Return stable identifiers so a later action can refer to the exact result rather than guessing from a display label.
Return evidence and useful errors
A successful write should return its operation identifier and resulting state. An error should distinguish validation, authorization, not found, rate limit, and transient failure where appropriate. Avoid returning a generic success string when the underlying operation is still pending.
For example, a delivery preparation tool might create a draft containing selected products and an intended recipient. The next step presents that draft for review. A separate commit action can use the approved draft identifier. This is an illustrative design that makes the approval target concrete and inspectable.
Handle retries without duplicate effects
Network failures can leave execution uncertain. The request may have reached the server even if the response never reached the caller. For consequential writes, use an idempotency strategy or an operation lookup so a retry does not create a second delivery, message, or order.
Keep credentials on the server and redact sensitive fields from logs. Tool results may include user-controlled text, so treat that text as evidence rather than instructions. Test both the tool contract and the orchestration behavior; a correct API can still be used incorrectly by an agent.
A tool contract worth shipping
- Names one clear operation with documented side effects.
- Validates arguments and authenticated access server-side.
- Returns stable identifiers, state, and categorized errors.
- Provides safe retry or reconciliation behavior.
- Exposes meaningful approvals and audit information.
