Agent and Tool Call Troubleshooting
Use this guide when an agent does not follow its instructions, cannot see a source, does not use a tool, uses an unexpected tool, or reports that an integration or tool is unavailable.
First checks
Confirm the correct agent: make sure the agent selected in Chat is the same agent you configured in Workshop.
Review instructions: confirm the agent instructions include the role, task, constraints, output format, and when to use each tool or source.
Check sources: confirm the needed file, folder, or source is attached and that the agent has permission to use it.
Check tools: confirm the needed tool is selected, connected, and available in the surface where you are using the agent.
Check model capability: use a model that supports tool calling when the agent needs tools or integrations.
Why a tool may not run
The tool is not selected for the agent, or Auto Tool Selection is off.
The model selected for the agent does not support tool calling.
The integration needs to be reconnected or reauthenticated.
The tool is available in one product surface but not in the surface you are using.
The agent has access to the tool, but the user's request did not clearly ask for work that requires that tool.
The tool call failed after it started because of an integration, permissions, input, provider, or response-format issue.
When an agent is not following instructions
Test one instruction at a time with a short prompt.
Move critical behavior into explicit instructions instead of relying on the agent to infer it.
Add the expected output format directly to the instructions.
Attach stable reference files or sources instead of relying on context from a previous chat.
Continue in the same chat when prior messages matter, or include the needed context again.
Collect before contacting support
Agent name and interaction method: Chat, Workflow, email, phone agent, API, or another surface.
Selected model and whether Auto Tool Selection was on.
Tools selected for the agent and connection status for each relevant tool.
Sources or files the agent should have used.
The exact request you sent, with secrets and private customer data removed.
What you expected the agent to do and what it did instead.
Screenshots of the agent settings, tool selector, source settings, inline tool-call details, and any error message.
If a tool call is involved, expand the visible tool-call details and include the tool name, input summary, result or error, and time. You do not need to find hidden internal tool-call IDs.
Share visible item, agent, chat, or workflow links when available, plus timestamp, screenshot, and error text. If the issue happened through the API, include the response X-Request-ID.
Support issue or enablement request?
Support issue: a documented agent, source, tool, or integration behavior is failing or producing an error after setup appears correct.
Enablement request: you want Hatz to design the agent, write prompts, build a workflow, train users, or choose an implementation strategy for your use case.
Support can help troubleshoot product behavior. Hands-on design, custom training, and implementation work may be routed to Use Case Workshop, Feature Fridays, Customer Success, or a paid engagement path.