Treat tool calls as an API contract
A model can request a tool, but the host must validate and execute it safely. Reliable agent tools have a precise name, input schema, permission category, and result shape. Ambiguous tools invite malformed arguments and confusing recovery.
The tool result should always tell the model what happened. A successful result contains useful evidence; a failed result identifies the rejected argument or operational problem in a form the next agent step can act on.
Make failure states distinguishable
Authentication failure, rate limit, malformed JSON, missing file, denied approval, and non-zero test exit are different conditions. Collapsing them into 'tool failed' causes needless retries and hides the correct fix.
Return a non-empty, structured string result after validating external data. Then keep a visible activity trail so the developer can see whether the problem belongs to the model, provider, tool host, workspace, or policy.
Design recovery before automation
Retries should be bounded and informed by the error. A syntax error may call for a corrected argument; a permission denial may call for a different plan; a rate limit calls for waiting or switching a provider profile, not repeating the same request.
Truss normalizes compatible-provider tool arguments and keeps tool activity, permissions, and cancellation visible so a failed call is recoverable evidence rather than a stuck agent state.
Next steps
Put it to work in your own workspace.
Pick the surface that fits your day, then connect a model you control.
FAQ
Questions developers ask before switching.
Why do coding-agent tool calls fail?
Common causes are malformed arguments, missing or incompatible tool schemas, provider formatting differences, permission denial, missing workspace files, authentication, and rate limits.
Should an agent retry a failed tool automatically?
Only when the error makes a safe retry meaningful. Bound retries and expose the failure so a developer can intervene when the problem is environmental or policy-related.