Best practices for tool and agent creation

This table shows the list of the best practices to follow when you build the tools:


Best Practice	Comment
Define the purpose of the agent. For example, specify whether the agent supports customers, retrieves data, or automates tasks. Specify the goals that you expect the agent to meet. Document your endpoint and describe why someone uses it. Explain product context. Define business terms, acronyms, and API Tools. Specify what each Tool returns. This information improves agent performance.	Do not expand the responsibilities of the Tool. Document the request payload and the response payload. Specify why the endpoint or the Tool must be invoked.
Include instructions for error handling in the Agent instructions. Specify how the Agent must respond when a Tool returns an error and how the Agent must continue the task.	For example: If all required data is collected / all Tools are invoked as intended,…
Use conditional sentences.	For example: When helping the user with payments, first ask for their employee id. When answering questions about products, display a table with name, location and last updated by headers. Before invoking Tools that perform update operations, confirm with the user before proceeding with using such Tools.
If you can, reduce the API scope to a describable range. As an alternative, create multiple Tools that cover specific domains of the endpoint.	Endpoints that return more than 20 parameters are difficult to document in a clear way. A large number of parameters increases the effort that is required to describe each field and the purpose of the endpoint.
For use cases that ask for a number, specify a count field in the API response.	A large language model does not count data. You must create a dedicated Tool for counting or expose the number as part of the API response.
Document API response content for any endpoint that returns a response payload that is larger than 10,000 tokens.
Start a new chat session each time you modify the Agent, the Tool, or the API data.	Changes to any content may not appear correctly in an existing chat session.