Agentic Data Plane

Troubleshoot Agents

Use this page to diagnose and fix common issues with AI agents, including MCP server connection failures, runtime behavior problems, tool execution errors, and gateway errors.

Read the Playground

The Playground tab shows each test as a Task card: status updates with token counts, one card per tool call with the tool’s name and latency, and an Artifact card holding the final response. Match what you see to the section that fixes it.

What you see What it usually means What to do

An answer with no tool-call card

The agent answered from the model alone, or invented the data.

Tighten the rule in the system prompt that says to call a tool before answering. See Agent not calling tools and Making up information.

A tool-call card for a tool you didn’t expect

The model chose among similarly named or vaguely described tools.

Reduce the tool count, rename tools, and sharpen their descriptions. See Calling wrong tools.

A tool-call card with a validation error

The model sent parameters that don’t match the tool’s schema.

Tighten the parameter descriptions and add an example to the system prompt. See Invalid parameters.

The same tool called again and again with the same parameters, or a task that ends at max iterations

The agent is looping.

Add a stop condition to the prompt and check what the tool returns, since its response never satisfies the agent. See Stuck in loops or exceeding max iterations.

An error headed Access denied

Authorization refused the request. That is neither a user rejection nor the upstream system failing. The agent, or the person testing it, lacks a permission the request needed. A failure that is not a denial says so instead, so read the title before you go looking for a policy.

Check which policy grants the action, for the agent’s own principal or for the caller. Where your environment offers the shortcut, the error carries a View policies link. See Manage Access Policies and Roles and Permissions Reference.

A tool-call card with an upstream error, and an Artifact that says the tool failed

The system behind the tool failed, and the agent reported it. For a prompt that says to stop when a tool fails, that is correct behavior.

Run the same tool from the server’s Inspector tab to confirm the failure is in the server, then retry. See Tool returns errors and Test an MCP Server’s Tools with the Inspector.

A tool-call card that times out

The system behind the tool is slow or unresponsive.

See Tool timeouts.

A run that takes more than about 10 seconds for a simple prompt

A slow model, slow tools, or a large context.

Read the latency on each tool-call card to find the slow step. See Slow response times.

A Live updates stopped notice

The Playground lost its live connection to the task and gave up reconnecting after about five minutes. The task may still be running.

Check the agent’s Transcripts tab later for the result. See Monitor Agent Activity.

A server under the Tools control marked Authentication required, Unavailable, or Couldn’t load tools

The agent can’t reach that server’s tools yet: you haven’t connected your account, the server isn’t available to the agent, or the tool list failed to load.

Click Connect and complete the authorization, ask an administrator to confirm the server exists and is enabled for the agent, or click Try again. See Monitor Agent Activity.

Connection issues

Fix issues that prevent agents from reaching their MCP servers.

MCP server connection failures

Symptoms: Agent starts but the tools don’t respond or return connection errors.

Causes:

  • The MCP server is disabled, or was deleted after the agent was created

  • A self-managed server is down or unreachable

  • The server’s upstream credentials or the calling user’s connection are missing or expired

  • The agent lacks permission to call the server’s tools

Solution:

  1. Open MCP servers in the sidebar and confirm the server exists and is enabled.

  2. Open the server and run one of its tools from the Inspector tab. A failure there is in the server or its upstream, not in the agent. See Test an MCP Server’s Tools with the Inspector.

  3. For a self-managed server, check your own server’s logs, and restart it if it isn’t responding.

  4. Confirm the agent has permission to call the server’s tools. See Manage Access Policies.

Prevention:

  • Test each server in the Inspector before you attach it to an agent

  • Monitor the health of self-managed servers you run

Runtime behavior issues

Resolve problems with agent decision-making, tool selection, and response generation.

Agent not calling tools

Symptoms: Agent responds without calling any tools, or fabricates information instead of using tools.

Causes:

  • System prompt doesn’t clearly specify when to use tools

  • Tool descriptions are vague or missing

  • LLM model lacks sufficient reasoning capability

  • Max iterations is too low

Solution:

  1. Strengthen tool usage guidance in your system prompt:

    ALWAYS use get_order_status when customer mentions an order ID.
NEVER respond about order status without calling the tool first.

  2. Review tool descriptions in your MCP server configuration.

  3. Use a more capable model from the supported list for your gateway.

  4. Increase max iterations if the agent is stopping before reaching tools, with rpk ai agent update <agent-name> --max-iterations <n>.

Prevention:

  • Write explicit tool selection criteria in system prompts

  • Test agents with the systematic testing approach

  • Use models appropriate for your task complexity

Calling wrong tools

Symptoms: Agent selects incorrect tools for the task, or calls tools with invalid parameters.

Causes:

  • Tool descriptions are ambiguous or overlap

  • Too many similar tools confuse the LLM

  • System prompt doesn’t provide clear tool selection guidance

Solution:

  1. Make tool descriptions more specific and distinct.

  2. Add "when to use" guidance to your system prompt:

    Use get_order_status when:
- Customer provides an order ID (ORD-XXXXX)
- You need to check current order state

Use get_shipping_info when:
- Order status is "shipped"
- Customer asks about delivery or tracking

  3. Reduce the number of tools you expose to the agent.

  4. Use subagents to partition tools by domain.

Prevention:

  • Follow tool design patterns in How MCP Servers Work

  • Limit each agent to 10-15 tools maximum

  • Test boundary cases where multiple tools might apply

Stuck in loops or exceeding max iterations

Symptoms: Agent reaches max iterations without completing the task, or repeatedly calls the same tool with the same parameters.

Causes:

  • Tool returns errors that the agent doesn’t know how to handle

  • Agent doesn’t recognize when the task is complete

  • Tool returns incomplete data that prompts another call

  • System prompt encourages exhaustive exploration

Solution:

  1. Add completion criteria to your system prompt:

    When you have retrieved all requested information:
1. Present the results to the user
2. Stop calling additional tools
3. Do not explore related data unless asked

  2. Add error handling guidance:

    If a tool fails after 2 attempts:
- Explain what went wrong
- Do not retry the same tool again
- Move on or ask for user guidance

  3. Review tool output to ensure it signals completion clearly.

  4. Increase max iterations if the task legitimately requires many steps, with rpk ai agent update <agent-name> --max-iterations <n>.

Prevention:

  • Design tools to return complete information in one call

  • Set max iterations for the task’s complexity, using the tiers in Max iterations

  • Test with ambiguous requests that might cause loops

Making up information

Symptoms: Agent provides plausible-sounding answers without calling tools, or invents data when tools fail.

Causes:

  • System prompt doesn’t explicitly forbid fabrication

  • Agent treats tool failures as suggestions rather than requirements

  • Model is hallucinating due to lack of constraints

Solution:

  1. Add explicit constraints to your system prompt:

    Critical rules:
- NEVER make up order numbers, tracking numbers, or customer data
- If a tool fails, explain the failure - do not guess
- If you don't have information, say so explicitly

  2. Test error scenarios by temporarily disabling tools.

  3. Use a more capable model that follows instructions better.

Prevention:

  • Include "never fabricate" rules in all system prompts

  • Test with requests that require unavailable data

  • Monitor transcripts for fabricated responses

Analyzing conversation patterns

Symptoms: Agent behavior is inconsistent or produces unexpected results.

Solution:

Review conversation history in transcripts to identify problematic patterns:

  • Agents calling the same tool repeatedly: Indicates loop detection is needed

  • Large gaps between messages: Suggests tool timeout or slow execution

  • Agent responses without tool calls: Indicates a tool selection issue

  • Fabricated information: Suggests a missing "never make up data" constraint

  • Missing early messages, or tool results replaced by short markers: Indicates the agent reduced its context to fit the model’s window (normal in a long conversation, not a fault)

Analysis workflow:

  1. Use Playground to reproduce the issue.

  2. Review full conversation including tool invocations.

  3. Identify where agent behavior diverged from expected.

  4. Check system prompt for missing guidance.

  5. Verify tool responses are formatted correctly.

Performance issues

Diagnose and fix issues related to agent speed and resource consumption.

Slow response times

Symptoms: Agent takes 10+ seconds to respond to simple queries.

Causes:

  • LLM model is slow (large context processing)

  • Too many tool calls in sequence

  • Tools themselves are slow (database queries, API calls)

  • Large context window from long conversation history

Solution:

  1. Use a faster, lower-latency model tier for simple queries and reserve larger models for complex reasoning.

  2. Review conversation history in the Playground tab to identify unnecessary tool calls.

  3. Optimize tool implementations:

    1. Add caching where appropriate

    2. Reduce query complexity

    3. Return only needed data (use pagination, filters)

  4. Click Clear context in the Playground tab if the context is very large.

Prevention:

  • Right-size model selection based on task complexity

  • Design tools to execute quickly (< 2 seconds ideal)

  • Set appropriate max iterations to prevent excessive exploration

  • Monitor token usage and conversation length

High token costs

Symptoms: Token usage is higher than expected, costs are increasing rapidly.

Causes:

  • Max iterations configured too high

  • Agent making unnecessary tool calls

  • Large tool results filling context window

  • Long conversation history not being managed

  • Using expensive models for simple tasks

Solution:

  1. Review token usage in transcripts.

  2. Lower max iterations for this agent.

  3. Optimize tool responses to return less data:

    Bad:  Return all 10,000 customer records
Good: Return paginated results, 20 records at a time

  4. Add cost control guidance to system prompt:

    Efficiency guidelines:
- Request only the data you need
- Stop when you have enough information
- Do not call tools speculatively

  5. Switch to a more cost-effective model for simple queries.

  6. Click Clear context in the Playground tab periodically.

Prevention:

  • Set max iterations for the task’s complexity, using the tiers in Max iterations

  • Design tools to return minimal necessary data

  • Monitor token usage trends

  • See cost calculation guidance in Cost calculation

Tool execution issues

Fix problems with timeouts, invalid parameters, and error responses.

Tool timeouts

Symptoms: Tools fail with timeout errors, agent receives incomplete results.

Causes:

  • External API is slow or unresponsive

  • Database query is too complex

  • Network latency between tool and external system

  • Tool processing large datasets in memory

Solution:

A managed agent waits up to 10 minutes for a tool call. The limit is fixed, so you can’t raise it.

  1. For a managed MCP server, narrow the request so the upstream system returns less, for example with filters or a smaller page size, or check whether the upstream service is slow.

  2. For a self-managed MCP server, fix the slow operation or set a shorter timeout in your own server so it fails fast with a clear error.

  3. Optimize external queries:

    1. Add database indexes

    2. Reduce query scope

    3. Cache frequent queries

  4. Add retry logic for transient failures in servers you run.

Prevention:

  • Test tools under load

  • Monitor external API performance

  • Design tools to fail fast on unavailable services

Invalid parameters

Symptoms: Tools return validation errors about missing or incorrectly formatted parameters.

Causes:

  • Tool schema doesn’t match implementation

  • Agent passes wrong data types

  • Required parameters not marked as required in schema

  • Agent misunderstands parameter purpose

Solution:

  1. Open the server’s Inspector tab and compare the tool’s input schema with the parameters the agent sent.

  2. For a self-managed server, make the schema match what the tool expects, mark required parameters as required, and add parameter validation.

  3. Improve the parameter descriptions and add an example, such as Order ID in format ORD-12345. For a managed server you can’t change the tool’s schema, so add the format and an example to the agent’s system prompt instead.

Prevention:

  • Write detailed parameter descriptions

  • Include format requirements and examples

  • Test tools with invalid inputs to verify error messages

  • Use JSON Schema validation in tool implementations

Tool returns errors

Symptoms: Tools execute but return error responses or unexpected data formats.

Causes:

  • External API returned error

  • Tool implementation has bugs

  • Data format changed in external system

  • Tool lacks error handling

Solution:

  1. Run the tool directly from the server’s Inspector tab, outside the agent.

  2. Verify the external system is operational.

  3. For a self-managed server, check its logs and return clear error messages from the tool.

  4. Update the agent’s system prompt to handle this error type.

Prevention:

  • Return clear error messages from tools in servers you run

  • Monitor external system health

  • Add retries for transient failures

  • Log all tool errors for analysis

Gateway errors

Agents and clients reach LLM providers and MCP servers through AI Gateway, so these errors come from the gateway rather than from the model or the tool.

Error What it means What to do

403 model_not_allowed

The request names a model that isn’t enabled on the LLM provider.

Enable the model on the provider’s Models tab, or use a model that’s already enabled. See Select models.

connection_required

A user-delegated MCP server needs the calling user to connect their account first. A tool call returns a failed tool result that carries the authorization URL. Other MCP requests return HTTP 424.

Open the authorization URL, connect the account, then call the tool again. See Configure User-Delegated OAuth.

token_expired

The user’s stored token for the upstream system expired and couldn’t be refreshed.

Reconnect the account under Connections, then call the tool again. See Configure User-Delegated OAuth.

scope_upgrade_required

The server requires a scope that the user’s connection wasn’t granted.

Reconnect and approve the extra scope. If the error returns after you reconnect, the upstream didn’t grant that scope. Check that the vendor app is allowed to grant it. See Scope upgrades.

429 budget exceeded

The agent reached its budget for the current period. The error uses the provider’s own rate-limit format: budget_exceeded for OpenAI-format providers, rate_limit_error for Anthropic, RESOURCE_EXHAUSTED for Google, and ThrottlingException for AWS Bedrock. Its message names the budget and when it resets.

Wait for the reset, or raise the budget. See Set a budget.

Monitor and debug agents

For comprehensive guidance on monitoring agent activity, analyzing conversation history, tracking token usage, and debugging issues, see Monitor Agent Activity.

Next steps