feat (docs): add 'prompt engineering with tools' section (#1941)

content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

@@ -142,3 +142,19 @@ There are several providers that offer pre-built tools that you can use out of t
   Vercel AI SDK? Please [file a pull
   request](https://github.com/vercel/ai/pulls) to add them to this list.
 </Note>
+
+## Prompt Engineering with Tools
+
+When you create prompts that include tools, getting good results can be tricky as the number and complexity of your tools increases.
+
+Here are a few tips to help you get the best results:
+
+1. Use a model that is strong at tool calling, such as `gpt-4` or `gpt-4-turbo`. Weaker models will often struggle to call tools effectively and flawlessly.
+1. Keep the number of tools low, e.g. to 5 or less.
+1. Keep the complexity of the tool parameters low. Complex Zod schemas with many nested and optional elements, unions, etc. can be challenging for the model to work with.
+1. Use semantically meaningful names for your tools, parameters, parameter properties, etc. The more information you pass to the model, the better it can understand what you want.
+1. Add `.describe("...")` to your Zod schema properties to give the model hints about what a particular property is for.
+1. When the output of a tool might be unclear to the model and there are dependencies between tools, use the `description` field of a tool to provide information about the output of the tool execution.
+1. You can include example input/outputs of tool calls in your prompt to help the model understand how to use the tools. Keep in mind that the tools work with JSON objects, so the examples should use JSON.
+
+In general, the goal should be to give the model all information it needs in a clear way.