AI engineering
Writing Tool Contracts an AI Application Can Use Reliably
Well-designed tools make AI actions easier to validate and debug. Define narrow inputs, explicit effects, useful errors, and stable result contracts.
Tool calling connects a model’s proposed action to application behavior. The tool definition therefore deserves the same care as a public API. The Model Context Protocol specification describes tools with names, descriptions, and input schemas. Those structures are useful building blocks, but the application must still define the real meaning, authority, and consequences of each operation.
Name the action and narrow its inputs
Prefer a tool that performs one understandable operation over a generic function that accepts arbitrary commands. Use identifiers with documented formats and distinguish search terms from exact record identifiers. Make units, date interpretation, and optional values explicit so the model does not have to infer important conventions.
Describe when the tool should be used and what it will change. If a tool only prepares a draft, say so. If it publishes a record or sends a message, make that effect unmistakable. Avoid combining lookup and mutation in a way that makes an apparently harmless request perform a write.
Design outputs for the next decision
Imagine a hypothetical project assistant with a create_task tool. A successful result should return the durable task identifier, its actual status, and a link or reference the interface can show. A validation error should identify the invalid field without exposing internal stack traces or unrelated customer data.
Return an explicit outcome for partial or uncertain execution. A timeout after a write request is not proof that the write failed. Include an operation identifier that the application can use to check status before retrying. Keep output size bounded so a search tool does not flood the next model call with an entire database export.
Validate the contract outside the model
Check argument types, permitted values, user authorization, and record ownership on the server. Tool descriptions guide model behavior but do not enforce security. Derive trusted context such as organization identity from the session rather than accepting it as an unrestricted model argument.
Build contract checks for malformed inputs, missing records, permission failures, duplicate requests, and service timeouts. Version breaking changes and keep callers compatible during rollout. Review real tool traces to identify repeated confusion: if the model consistently supplies a title where an identifier is required, the interface or the preceding lookup step may need to be clearer.
