Tool Schemas, Validation, and Idempotency
Use narrow tool schemas with enums, length limits, required fields, and explicit descriptions. Validate again in application code, including business constraints that schemas cannot express. For side-effecting operations, add idempotency keys or a deduplication record so retries do not create duplicate payments, tickets, or emails.
Separate read tools from write tools. A write tool should have explicit authorization and often require user confirmation. Record who requested the action, what arguments were accepted, what policy was applied, and the result. Avoid storing unnecessary sensitive arguments in audit logs.
Validate and deduplicate a side effect
async function createSupportTicket(input, context) {
const parsed = TicketInput.safeParse(input);
if (!parsed.success) throw new Error("Invalid ticket arguments");
return db.withIdempotencyKey(
context.idempotencyKey,
() => tickets.create({
userId: context.userId,
subject: parsed.data.subject,
body: parsed.data.body
})
);
}💡
TicketInput and withIdempotencyKey represent application-owned validation and deduplication helpers. Implement them using a trusted schema validator and a durable unique key in the database.Key Takeaways
- Use narrow schemas and validate again in the executor.
- Make side effects idempotent where possible.
- Audit sensitive actions and require confirmation where appropriate.
Knowledge Check
Why use an idempotency key for a side-effecting tool?