AI tool contracts: design inputs and outputs that work

An AI tool contract defines what a tool accepts, what it does and what it returns. Clear contracts reduce ambiguity between the model's intention and the application's action. Validate inputs and permissions in code even when the model usually supplies well-formed arguments.

Prefer an explicit action

Imagine a tool named manage_customer with a free-text instruction. It could mean reading notes, changing a status or sending a message. Separate capabilities such as get_customer_summary and prepare_customer_reply make the intended behavior easier to inspect and authorize.

A write tool should identify the exact record and permitted fields. Avoid accepting a display name as the only identity when several customers can share it.

Define the important fields

• Required input: record IDs and parameters the action cannot proceed without.
• Validation: allowed values, format constraints and business rules.
• Side effects: what changes outside the model conversation.
• Result: structured status, record identifiers and useful error details.
• Recovery: whether repeating the request is safe and how to reconcile it.

Make missing data explicit. An empty result should distinguish no matching records from an unavailable connection. Those conditions imply different next steps.

Return evidence, not reassurance

A response saying everything went well gives the agent little to verify. A response containing a saved draft ID, account ID and status gives it a basis for accurate reporting. Keep sensitive payloads out of logs when identifiers are sufficient.

For asynchronous work, return a job identifier and a pending state. Provide a separate way to inspect completion rather than encouraging the agent to infer it from request acceptance.

Test misuse as well as normal use

Try a missing ID, an unauthorized destination and an invalid field value. Confirm the tool rejects them before side effects occur. Then test a valid request to ensure the controls do not block useful work. A good contract makes correct behavior straightforward and incorrect behavior visible.

Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.