8.2 Agent Tool Mismatch & Interceptor Timeout Diagnostics

Step-by-step diagnostic tree for resolving agent tool timeouts and parameter schema mismatches.

When the Agent and the Interceptor Disagree

Every tool call an agent makes during a test run goes through the in-process interceptor on port 4790, which matches the requested tool name and arguments against whatever a step configured – a MOCK_TOOL_RESPONSE stub, an EXPECT_TOOL_CALL assertion, or both – and resolves in roughly 2 milliseconds since it never leaves the process. A “tool mismatch” failure means the interceptor saw a call that didn’t line up with what a step expected, and which of a few specific ways it didn’t line up determines the fix.

Ranked by How Often Each Is the Real Cause

• 1. Tool name mismatch – the single most common cause. Tool names are matched case-sensitively against what the agent actually registered, not against what its system prompt says to call – a prompt that says “use the getUserSettings tool” is meaningless if the agent’s own tool schema registers it as get_user_settings. Check the agent’s tool registration, not just its prompt wording, before assuming the interceptor is misconfigured.
• 2. Argument shape mismatch under the wrong matchMode – EXACT requires the call’s arguments to equal the expected object field-for-field, PARTIAL only requires the named keys to match and ignores any extra ones the agent legitimately included, and SCHEMA validates the arguments against a JSON-schema-shaped expectedArgs rather than literal values. A lot of “mismatches” here are really just EXACT being too strict for an agent that adds a harmless extra field – switching the step to PARTIAL or SCHEMA is usually the right fix, not changing the agent.
• 3. Tool call timeout – verify the agent is actually configured to reach the interceptor on port 4790 in the first place. Because the interceptor is in-process, a call that takes real network-latency time to fail is a sign the agent bypassed the mock and attempted an external call, not that the mock itself is slow.
• 4. Sequence or count assertions failing independently of any single call being wrong – EXPECT_TOOL_SEQUENCE (STRICT/SUBSEQUENCE/SET modes) and EXPECT_TOOL_CALL_COUNT fail on the shape of the whole trajectory, not one call. A STRICT sequence assertion breaking when the agent legitimately re-checks something mid-run is usually a sign the assertion mode is stricter than the agent’s real, acceptable behavior – SUBSEQUENCE or SET is often the better fit than trying to make the agent more deterministic than it needs to be.

- action: EXPECT_TOOL_CALL
  toolName: get_user_settings
  argsMatchMode: SCHEMA
  expectedArgs:
    required: ["userId"]

This asserts the agent called get_user_settings with at least a userId argument present, without caring about its exact value or whether other optional arguments were also included – the right level of strictness for most real tool-call checks, reserving EXACT for the rare case where the literal argument values themselves are the thing under test.

Before Assuming the Agent Is Broken

• A mismatch on a case that used to pass is worth checking against the case’s recorded golden trajectory (if it has one) before touching the assertion – a real behavior change and a correct-but-different call sequence can look identical from a single failed step.
• MOCK_TOOL_RESPONSE stub matching uses the same matchMode field as EXPECT_TOOL_CALL – if a stub itself isn’t matching, the agent’s real call is falling through to no mock at all rather than getting a response, which usually shows up as the agent inventing an answer or erroring, not as a clean tool-call failure.