Designing Tool-Friendly APIs

Giving an assistant access to an API does not guarantee it will know how to use it correctly. Suppose a support manager asks an assistant to assign a delivery ticket to Alice. The API already supports ticket search, user lookup, and assignment, yet the assistant chooses the wrong search operation, guesses a user ID, and interprets an accepted request as a completed assignment.

An API can be easy to call from handwritten code and still be difficult to use as a model-facing tool.

This chapter explains how operation boundaries, descriptions, schemas, results, and errors help a model select the right operation and supply meaningful arguments. It also covers how to maintain a tool catalog as a dependable interface.