Ask, Plan, Act: Agent Roles That Decide What Your MCP Agent May Do

An AI agent with access to your API can read data and change it. The question is not whether it can do something, but whether it should, right now. OrcA answers that with three roles: Ask, Plan and Act. You choose how much the agent may do in each conversation, and OrcA enforces it in the tools the model receives, not only in its instructions.

TL;DR

• Ask: the agent explores and answers with read-only tools. Nothing can change.
• Plan: the agent investigates, uses capability planning, and ends with a numbered plan for you to review. Nothing can change.
• Act: the agent gets every tool. Changes still ask for your approval by default.
• Enforced, not suggested: in Ask and Plan, tools that change data are never sent to the model, so it cannot call them.
• Works with any MCP server, and gets better with a HAPI capability graph.
• Available since OrcA 0.5, in the Chat header and the Harness tab.

The problem: one mode for every intention

People talk to an assistant with different intentions, often in the same conversation:

1. "What appointments do I have?" They want an answer.
2. "How would I move the one on Tuesday?" They want to see what it takes.
3. "Move it to Friday at 10." They want it done.

Most chat setups give the model the same tools for all three. If every tool is available, a question can still end in an action: the model "helpfully" reschedules while you were only asking how. Instructions such as "don't change anything unless asked" help, but a model can misread or ignore them.

An analogy: the rule book and the instructions at the desk

Picture the reception desk of a clinic.

• The capability graph is the clinic's rule book. "To book, you need an identified patient, a chosen doctor, a chosen time, and the patient's confirmation." It is true for everyone, every day. It describes the API.
• The role is what you tell the assistant at the desk today:
  • Ask: "Just answer questions. Don't touch the calendar."
  • Plan: "Work out what needs to happen and show me first. Don't touch the calendar yet."
  • Act: "Go ahead and book it." The rule book still applies, and you still approve the changes.

The rule book cannot know whether you want changes today. Only you can, and the role is how you say it.

Why roles still matter with a capability graph

The HAPI Capability Graph tells an agent what each operation requires and produces, and computes plans. So why add roles?

1. The graph advises; it does not prevent. capability_context and capability_plan are read-only guidance. With every tool loaded, a model can still skip the plan and call the cancellation tool directly. Roles remove that possibility: in Ask and Plan, the model never receives tools that change data.
2. Not every server has a graph. Ask and Plan rely on the standard MCP read-only hint, so they protect any server, including third-party ones.
3. The API is the same; your intention changes. The same contract serves "show me", "plan it" and "do it". The graph describes the API; the role describes the conversation.
4. Plans need a human checkpoint. A computed plan is still a proposal. Plan mode makes the review an explicit step, and Proceed turns it into action.

	Capability graph	Role	Approvals
Answers	What does the API need, and in what order?	What may the agent do right now?	Should I confirm this specific call?
Decided by	The contract author	You, per conversation	You, per tool or per workspace
Enforcement	Advice to the model	Tools hidden from the model	OrcA asks before calling

What each role does in OrcA

	Ask	Plan	Act
Tools the model receives	Read-only tools, tool search, capability_context and capability_plan	Same as Ask	Every tool
Can it change data?	No	No	Yes, with approval by default
How it uses the graph	To explain what an action would need	To build a plan: goal, steps, missing facts, confirmations	To follow the plan and re-plan after a failure
Ends with	An answer	A numbered plan and a Proceed button	The result, or the next question

Three details make roles reliable rather than decorative:

• Hidden everywhere. A tool a role hides is removed from the request, from the catalog of tools not loaded yet, and from search results.
• Refused if named. If an old message makes the model call a hidden tool, OrcA refuses the call and tells the model which role is active.
• Remembered per chat. Each conversation keeps its role, and saved chats restore it. New chats start with the role in orca.chat.role.

When to use each role

Use Ask when you explore or test.

• "What can this API do?", "Which pediatricians work in Morelia?", "What are my appointments?"
• When you connect a new or unfamiliar MCP server and want to see how the model uses it, with zero risk.
• When you demo OrcA or share the chat with someone less familiar with the API.

Use Plan before multi-step or irreversible changes.

• "Move my Tuesday appointment to Friday", "Book for my daughter and cancel mine".
• When you want to see the order of steps, the missing information (a slot? a confirmation?), and which calls will ask for approval.
• When you review a contract: Plan shows whether the capability graph leads to the right steps.

Use Act when the steps are clear.

• After Plan, with Proceed.
• For simple, routine actions where a plan adds nothing.

A typical session flows Ask → Plan → Proceed (Act): understand, review, then do.

How to use roles in OrcA

1. Connect a server in MCP Servers and open OrcA › Chat.
2. Pick the role above the conversation: Ask, Plan or Act. The same control is in the Harness tab.
3. In Plan, read the numbered plan. When it looks right, click Proceed: OrcA switches to Act and sends "Proceed with the plan."
4. In Act, approve each change on its card: Allow Once, Allow for This Session, Always Allow in This Workspace, Never Allow or Deny.
5. Set the default for new chats with orca.chat.role (ask, plan or act; the default is act).

Roles, facts and approvals work together

• Facts carry across roles. On capability-graph servers, the Context tab keeps the facts of the chat. Facts you verify while you Ask or Plan are still there when you Act, so the plan does not start over.
• Approvals still apply in Act. The Harness tab's presets (Request approval, Auto-approve read-only, Allow all) and your workspace rules decide when OrcA asks before a call. The role decides which tools exist; approvals decide when to check with you.
• Traffic shows everything. Every model round and tool call, in every role, is recorded in OrcA Traffic.

Make your API role-friendly

Roles rely on one piece of contract metadata: whether a tool is read-only. HAPI marks GET operations as read-only and every POST, PUT, PATCH and DELETE operation as potentially destructive. If your search runs over POST, add x-readOnlyHint: true, or Ask and Plan will hide it. How to Design OpenAPI Contracts That Guide AI Agents covers this, and OrcA's agent-readiness checks flag it in the editor.

Frequently asked questions

What are the Ask, Plan and Act roles in OrcA? Chat roles that decide what an AI agent may do with your MCP servers. Ask answers with read-only tools, Plan ends with a plan without changing anything, and Act may use every tool, with approvals.

Why use roles if I already have a capability graph? The graph describes what the API needs and in what order, but it never prevents a call. The role decides what the agent may do now, and in Ask and Plan the model never receives tools that change data. Roles also protect servers without a graph.

Is a role just an instruction in the prompt? No. OrcA removes hidden tools from the request, the deferred catalog and search results, and refuses calls to them. The instruction only explains the role to the model.

When should I use Ask, Plan or Act? Ask to explore or test, Plan before multi-step or irreversible changes, and Act when the steps are clear, usually after Plan with Proceed.

How do roles relate to tool approvals? Roles decide which tools exist; approvals decide when OrcA asks before using them. In Act, the default preset asks before any tool that may change data.

Try it

• ⬇️ Install: OrcA MCP on the VS Code Marketplace, or code --install-extension la-rebelion-labs.orca-mcp.
• 🧭 The harness behind it: OrcA 0.4: An MCP Agent Harness in VS Code.
• 📘 Agent-ready contracts: How to Make APIs AI-Ready with Intent-Based Contracts and Arazzo Workflows.

The graph knows the way. The role decides whether to take it today.

Be HAPI, and enjoy building!