Tool reliabilityChecklist5 min

Flatten tool schemas for more reliable arguments

A practical pattern for making model-generated tool arguments easier to validate and debug.

Real example

Example: replace nested CRM payloads with action fields

A CRM assistant tries to create a follow-up task with nested objects for contact, company, deal, owner, priority, and due date. The model regularly misses one nested field.

Flatten the tool input to contactId, dealId, dueDate, priority, and note. The server derives company, owner, workspace, and permissions from trusted records.

Tool calls become easier to validate, logs become readable, and the model stops inventing nested ownership data.

Flat tool payload

type CreateFollowUpInput = {
  contactId: string;
  dealId: string;
  dueDate: string;
  priority: "low" | "normal" | "high";
  note: string;
};

Tutorial path

How to implement it

Step 01

Replace nested objects with explicit top-level fields when possible.

Step 02

Use IDs, enums, and short strings instead of free-form nested payloads.

Step 03

Move derived values into server-side lookup logic.

Step 04

Return validation errors that explain exactly which field failed.

Step 05

Add fixtures for the most common tool argument mistakes.

Checklist

Ready when these are true

No avoidable nested argument objects

Enums for workflow state

Server derives trusted values

Validation errors are logged

Fixtures cover malformed calls

Field notes

What matters in practice

Deeply nested tool schemas increase validation failures and make logs harder to read.

Flat inputs make it easier to reject unsafe actions and explain required fields.

Complexity belongs in your server code, not in model-generated arguments.

Avoid these mistakes

Common failure modes

Do not ask the model to construct nested database records.

Do not accept ownerId, organizationId, or role values from tool arguments.

Do not hide validation failures from the user or logs.

Practical tip

If a value can be derived from a trusted ID, derive it on the server instead of asking the model to send it.

Apply this to a build