Reference
Errors and limits
What a failed tool call returns, what to do about it, and the sizes and times to plan for.
How an error comes back
A tool that fails returns a normal MCP result marked as an error. Its text is the same error body as the API's, so an agent can read the code and what to do:
Code
Every code is on the Errors page. The ones an agent meets most:
| Code | What to do |
|---|---|
STALE_OBSERVATION | The screen changed since the screenshot; nothing ran. Take a new screenshot, then act again |
CONTROL_HELD | A person has control in the live view; nothing ran. Wait, then take a new screenshot |
OUTCOME_UNKNOWN | It may or may not have happened. Take a screenshot before trying again |
SCREEN_NOT_RUNNING | The screen is stopped or starting. Start it in the dashboard, or wait |
PERMISSION_DENIED | The token or key lacks the permission, or that screen. Grant it |
ACCOUNT_PENDING | The account waits for approval. Stop and tell the user |
RATE_LIMITED | Too many calls. Wait retry_after seconds |
A call with no token, or an expired one, answers 401 and the app signs in again. A token without the permission a tool needs answers 403 with insufficient_scope (Sign-in and permissions).
Limits
| What | Limit |
|---|---|
| Any tool call | Answers within 30 seconds |
act | 1 to 20 actions per call |
wait | Up to 20 seconds |
exec | The last 8 KiB of output inline; a longer run returns an exec_id |
exec_status | Waits up to 25 seconds for the command to finish |
read_file, write_file | One file up to 64 KiB, as text or base64 |
read_tree | Up to 1,000 elements per call |
| Images | One per result, WebP under 105,000 bytes |
- 30 seconds keeps every call inside the 60-second limit some agent apps set. Longer work goes through
execandexec_status. - One image per result, under 105,000 bytes, keeps results inside claude.ai's size limit. Use
zoomto read small text at full resolution. - Bigger files go through the API, the SDK or
exec(for examplecurlon the screen). - Input is queued per screen, so two agents on one screen never type into each other; a person taking control stops both.
Plan-wide limits, such as how many screens and calls per minute: Limits.