Cursor Agent Overview: Tools, Models & How It Works

Every Agent run sits on three pieces: the instructions it follows, the tools it can call and the model doing the reasoning. Change any one and the run behaves differently. The stack below names each piece.

Which of the three you changed matters, because they fail differently. A bad result right after a model switch is a model problem. A bad result on the same model, in a repo where somebody added a rule last week, is an instructions problem, and it will follow you onto every model you try next. My default when a familiar task starts going wrong is to read the rules that apply to those files before I touch the model picker.

Agent works through a fixed set of tools: it can search your indexed repo, open and patch files, run shell commands, drive a browser, fetch the web and pause to ask you a question.

Two of those rows do not look like codebase tools, which is probably why they get skipped. Fetch rules means some of what steers the agent arrives mid-task rather than sitting in the opening context. Image generation writes into your project's assets/ folder and shows the result inline in chat, which is a different job from the screenshots the browser takes.

The shell row carries the one setup detail that catches people. Cursor uses the first available terminal profile by default, which is fine until that is not the shell your project's scripts expect, at which point commands fail in ways that read as the agent getting it wrong. Set it from the Command Palette with Terminal: Select Default Profile.

There is no cap on how many tool calls a task can make. That is a real capability, and it is also why a vague prompt can spend a lot of usage before anything stops it, since nothing in the loop is watching the clock for you. Cheaper to write the stopping condition into the prompt than to sit and watch for it.

Agent is the doer: it edits and runs commands. Ask stays read-only for explanation. Plan Mode, Debug Mode and Design ModeA way to point at an element in Cursor's built-in browser and change it directly, instead of describing it in words. Press Enter for the full definition. are specialized agent workflows for planning, runtime-evidence debugging and visual UI iteration. Agent Review checks diffs after edits. Pick the mode that matches whether you are exploring, executing, debugging or reviewing.

⇧+⇥ rotates between them from the chat input, and it is the quickest way to find out you have been in the wrong one. A read-only Ask reply when you wanted the change looks a lot like the model ignoring you, and so does an edit when you only wanted a read. Check the mode before you rewrite the prompt.

Start with Auto modeA router that reads your prompt and picks a model for you, defaulting to Composer; you steer it with cues like "quickly" or "carefully". Press Enter for the full definition. as your daily driver: it offboards model selection entirely. Since 2026-07-22, Auto is powered by Cursor Router on Teams and Enterprise plans. A classifier runs on each agent request and routes it by task type and complexity, so what you pick is an optimization mode - Cost, Balance or Intelligence - rather than a model. Cost keeps the previous Auto routing logic and its bundled Auto pricing; Balance and Intelligence bill at the routed model's rate. The router is on by default for Teams plans, and Enterprise admins enable it from the dashboard. Turn Auto off only when you need a specific model's characteristics.

When you do choose, decide in two steps. First, thinking vs non-thinking: reach for a thinking modelA reasoning model (shown with a brain icon in Cursor's picker) that spends extra compute before answering; reach for it on complex, nuanced work and a standard model for fast, simple tasks. Press Enter for the full definition. for plans, complex environments and security or codebase scans (slower but smartest, and overkill for simple tasks). Then weigh model traits. GPT-5.x is verbose and can overthink a simple task, but it's excellent at writing documentation and clear natural-language explanations.

Restore a checkpoint. Agent snapshots your modified files automatically before significant changes, and each snapshot sits in the chat timeline: click one to preview the files at that point, then restore to revert them. A Restore Checkpoint button appears on previous requests too.

Checkpoints are stored locally and separate from Git, and Cursor is explicit that they exist to undo Agent changes rather than to do version control. So they cover the exploratory case well: three attempts at a refactor, none of them right, back to the state before the first. They do not cover the case where the work needs to leave one laptop.

I would still branch before a long agent session, checkpoints or not. A checkpoint gets you out of a bad hour on your own machine, and a branch is what makes the same work reviewable by anyone else.

Yes. Type your next instruction while Agent runs and press Enter to queue it. Queued messages appear in order below the active task, you can drag to reorder them, and Agent works through them once it finishes. ⌘+↵ (Ctrl+↵) sends immediately and bypasses the queue.

Those two are worth keeping separate in your head. An immediate message gets appended to your most recent message and processed right away, which makes it the tool for redirecting a run that is heading somewhere wrong. Queueing is for the follow-up you already know you want. Reach for the immediate path on ordinary follow-ups and a focused run turns into a thread that has changed subject three times.

A few habits separate a clean Agent run from one that wanders. Point it at the right files, tell it how to know it succeeded, gate the risky commands and start fresh when the context fills up.

• @-mention the files and folders that matter instead of making Agent search blind.
• State success criteria: a test command, URL or expected behavior.
• Approve terminal commands that touch production, secrets or billing.
• Start a fresh chat when context fills with failed attempts.

The last habit is the one I would build first, and it is the least intuitive of the four. Starting a fresh chat feels like throwing work away, especially when the agent nearly had it. What you are throwing away is a transcript of failed attempts that the model now reads as context, and that transcript is what keeps it circling the same wrong answer.