Skip to main content

Agent and Tool Call Troubleshooting

Check status before changing the setup

Read the latest task status and tool result. Waiting for an approval is different from a failed tool. A selected tool, a discovered tool and a tool that actually ran are different states.

Identify where the task runs: interactive Chat, a saved Agent, a saved automation or a classic workflow. Interactive Chat can discover permitted tools during a run; saved automations use their saved tools. Check the configuration for that surface.

Use the exact message to identify an execution safeguard or usage restriction. If a tool may already have sent or changed information, check the external result before replaying it. Contact Support when the outcome remains uncertain.

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 connected and available in the surface you are using. Manual and classic configurations may require selecting it; an interactive chat with automatic discovery can find permitted tools.

  • Check model capability: use a model that supports tool calling when the agent needs tools or integrations.

Why a tool may not run

  • For a manual or classic setup, the required tool may not be selected. In an interactive chat, check whether automatic discovery is enabled and whether the tool is permitted and available.

  • 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 relevant settings, tool details and error. Remove credentials, signed URLs and private content from all screenshots and diagnostic details.

  • For a tool call, expand the visible details and include the tool name, input summary, result or error, and time.

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 Feature Fridays, Customer Success, or a paid engagement path.

Check whether Chat is waiting for approval

Look for a card asking you to review a proposed action. In this walkthrough, Chat waits while Alex reviews the proposed Skill and its invocation setting. Choosing Save skill completes the action and produces a confirmation in Chat. Choose Dismiss if you want to revisit the proposal.

Follow a running tool step

While Chat is working, the activity line shows its current step. The square Stop control appears in the composer. If you let the example finish, you can expand the Python activity and check the result against the original entries.

Did this answer your question?