A tool needs a clear contract

IDEA 1

One tool, one understandable job

A tool contract explains its purpose, accepted arguments, result fields, and possible effects. readRoom(id) reads one room. A separate booking tool would have a different effect and permission requirement.

Give the caller enough detail to choose correctly. ‘Do room stuff’ leaves the ID format and side effects unclear. Our contract accepts a nonempty string ID of at most 20 characters and returns an ok flag plus either a room or an error.

Research connection: Toolformer studied training a model to select API calls and use their results. Here you are writing the application that checks and executes a request. Adding readRoom to a program does not train a model, and a tool-trained model still needs execution boundaries.

Inspect the contract

1. Purpose. Retrieve one room by its known ID.
2. Argument. The caller supplies a bounded, nonempty string.
3. Result. The caller receives a record or a labeled error.

The allowed catalog is fictional and read-only.

A useful description

// readRoom(id)
// id: string, length 1..20
// success: { ok: true, room }
// missing: { ok: false, error: "not-found" }
// effects: reads only

A signature alone names the operation. These additional rules tell the controller how to validate a request and interpret its observation.

Think it through: Which detail identifies a tool's action boundary?

IDEA 2

Validate arguments before execution

JSON can be syntactically valid and still contain an invalid request. The object {id: 42} has a valid structure as JavaScript data, but 42 violates this tool's string-ID contract.

Check argument type and range before calling the tool. The tool also checks its own boundary, because callers can be mistaken. Neither check proves the selected ID answers the user's question or gives permission for a different action.

Stop a bad argument early

1. Type. A numeric ID fails this string-only contract.
2. Range. An empty or very long ID is rejected.
3. Dispatch. Only a valid argument reaches readRoom.

Validation is executable code, not an instruction hoping the caller behaves.

Reject before calling

if (typeof id !== "string" || id.length < 1 || id.length > 20) {
  return { status: "invalid-argument", room: null };
}

|| means any listed failure is enough to reject. JavaScript checks left to right, so the length checks are reached only when the type check did not reject the value.

Think it through: The request contains valid JSON with id: 42. What has passed?

IDEA 3

Return useful observations and explicit errors

A tool should return information the controller can use. An ok flag distinguishes an obtained room record from a missing ID. An error label lets the controller decide whether to ask for clarification, stop, or use a different permitted route.

A room with seats: 0 is still a record. A missing record is a different state. Avoid replacing every unusual result with ‘success’ or retrying every not-found result; repeating the same absent ID does not create evidence.

Three outcomes, three meanings

1. Invalid argument. The call should not run at all.
2. Missing record. A valid call found no matching ID.
3. Observed record. Return the actual fields for the next check.

These result shapes are authored for this exercise.

Preserve the distinction

const result = tools.readRoom(id);
if (!result.ok) return { status: result.error, room: null };
return { status: "found", room: result.room };

The controller translates the tool observation into its own small output schema without inventing a record or erasing an error.

Think it through: readRoom returns not-found for a valid ID. What is justified?

Put it into practice

Reject invalid IDs before a call, then preserve found or not-found observations.

1. Inspect the readRoom contract beside the editor.
2. Run the starter with the numeric-ID case and inspect its unwanted call.
3. Insert the argument guard before readRoom.
4. Check that the invalid case makes zero calls and the missing case makes exactly one.

Your next experiment: Try an empty string and then a 21-character ID. Which boundary rejects each?

A tool contract covers arguments, observations, failures, and effects—not just a function name.

Key terms

Schema

Rules for the shape and types of a data value.

Validation

Executable checks that determine whether a value satisfies stated rules.

Sources and scope

Original Stemtiq teaching, reviewed 2026-09-14. The named researchers and organizations do not endorse this course. Classroom cases are authored exercises, not published findings.