How to Use the Amazon Bedrock Converse API Tool Use Planner Prompt to Build a Reliable Tool Calling Assistant

The Converse API on Amazon Bedrock gives you one request format across many models, and it supports tool use: you describe tools with JSON schemas, the model asks to call one, your code runs it, and you send the result back. The pieces are simple, but the details trip people up. Messages have to alternate correctly, every toolResult has to match its toolUseId, errors need a status the model can explain, and not every model supports every toolChoice option. The Amazon Bedrock Converse API Tool Use Planner: toolConfig and toolSpec JSON Schemas, toolChoice Options, the tool_use Stop Reason Loop, toolResult Error Status, Inference Profiles, and boto3 Code prompt plans the whole loop the way an AWS generative AI engineer would and gives you boto3 code and a test checklist.

What the prompt produces

1. A toolConfig block with one toolSpec per tool and strict JSON schemas.
2. A toolChoice decision between auto, any, and forcing a named tool.
3. A system prompt that states your conversation rules.
4. The request loop that handles the tool_use stop reason and sends toolResult blocks back.
5. Error handling that returns toolResult blocks with an error status and retries throttling.
6. Argument validation before any backend call runs.
7. A test checklist covering each path, a forced error, and token usage logging.

How to fill the inputs

ModelId is the model ID or inference profile ID copied from your Bedrock console, plus the region and whether model access is enabled. The prompt reads the ID from configuration and never guesses one.

ToolList describes each tool: its name, what it does, its parameters with types and allowed values, and the backend call behind it.

ConversationFlow explains what users ask, which tool should run when, and which questions the model should answer without a tool.

ErrorPolicy says what happens on timeouts, records that do not exist, permission problems, and bad arguments.

RuntimeLimits sets the maximum number of tool rounds, the latency budget, streaming or not, and logging rules for personal data.

Reading the example output

The example builds an internal IT helpdesk assistant with two tools: one looks up a ticket and one opens an MFA reset request. Each toolSpec has a description written for the model, saying when to use the tool and when not to, and a schema with a ticket ID pattern, an enum for the reset method, and additionalProperties set to false.

The toolChoice section picks auto, because policy questions should be answered without a tool. The loop calls converse, appends the assistant message, runs each toolUse block, and sends one user message with all the matching toolResult blocks, stopping at end_turn or after three rounds. The error section shows how a missing ticket or a timeout becomes a toolResult with an error status and a short message, so the model can apologize clearly instead of inventing an answer. The validation section refuses reset requests for email addresses outside the company domain, and the test list includes a question that should trigger no tool at all.

Tips for better results

• Write tool descriptions for the model, not for developers. Say when not to use a tool.
• Keep schemas strict with enums, patterns, and required fields.
• Cap the number of tool rounds so a confused model cannot loop forever.
• Log token usage per round so you can see what each conversation costs.

Mistakes to avoid

• Do not hardcode a model ID copied from a blog post. Use the one from your console.
• Do not run a tool just because the model named it. Check it against your tool list.
• Do not log full emails or other personal data in debugging output.

Who it is for

Backend engineers building assistants on AWS, platform teams standardizing on the Converse API across models, solution architects preparing a proof of concept, and developers moving from a single vendor SDK to Bedrock.

A practical routine

Run the prompt when you add a new tool, update the schemas and tests together, and replay the test checklist before each deployment so tool behavior does not drift when you switch models.

Related PromptDig links

Plan your next Bedrock assistant with the Amazon Bedrock Converse API Tool Use Planner: toolConfig and toolSpec JSON Schemas, toolChoice Options, the tool_use Stop Reason Loop, toolResult Error Status, Inference Profiles, and boto3 Code prompt. For more AI tool prompts, Browse more prompts. If you have a developer prompt that saves you time, Share a prompt.