Handing an API to an AI doesn’t mean it understands that API. A human developer can read the context, ask a colleague and work out what a parameter means. An agent in the middle of a task has to decide, from a limited description, what to call, what to fill in and when to stop.
Name tools after business actions
Anthropic’s article on writing tools for agents stresses clear functional boundaries, meaningful return information and improving tools through evaluation.[1] Following that, we suggest tool names should express business actions, so the model isn’t left guessing between many generic interfaces with similar meanings.
“Read the delivery status of a given order”, for instance, is clearer than “process order data”. The first can spell out the order-number format, the fields it may read and the statuses it returns; the second easily ends up doing lookups, edits and notifications at once, so its boundaries are hard to judge. The number of tools should follow from the real tasks.
Read first, then suggest, and only then act
For processes that change business state, separate reading information, generating suggestions and submitting actions. A support agent checking shipping doesn’t need permission to edit orders; drafting a rescheduling plan doesn’t need to confirm the change straight away. Split apart, permissions can be narrower and tests can pinpoint problems more easily.
A submitting tool should require complete, explicit parameters: the record being acted on, the fields to change and the approval it relies on. Identity and permissions must be verified by the system, not taken on trust from what the model passes in. When a person confirms, the interface should show the exact change about to happen, rather than asking them to approve a vague “continue”.
Results should support the next decision
Returning just “success” usually isn’t enough. The system should return a record ID that can be checked, the actual state and when it completed; on failure, it should say whether it was a bad parameter, missing permission, a record that doesn’t exist or a temporary outage. The kind of error decides whether the next step is to ask, stop or retry.
Say the ticketing API times out: the model shouldn’t assume the submission failed and create it again. For actions like this, use an idempotency key at the application level, and check the previous attempt’s result with a lookup. Running the same request twice should never quietly create two tickets. That’s the responsibility of the API and the business system, and can’t all be handed to the prompt.
Test the descriptions on real tasks
Even with clear tool documentation, you still need to verify that the agent actually picks the right tool, passes the right record and reads the result correctly. Build a set of tasks with similar orders, missing fields and API failures, and check the whole run, not just the final reply.
Whenever you find an error, first locate it: tool naming, parameter design, permission boundaries or business rules? Only once the cause is clear should you change the description or the implementation. In the long run, a set of small tools with clear boundaries, tested on real tasks, is easier to maintain than one interface that does everything and can’t be explained.
Check one tool that can write: can users see what it will change, can the result be checked after a failure, and does calling it twice create duplicate business records?
References
This article combines public sources with SWYZL & Co.’s recommended methods. The hypothetical scenarios illustrate design thinking and do not represent client results.
