How methods become actions
The rules by which MentorAgent turns your methods into actions, names them, turns them on or off, adds up roles and confirmations, and publishes them.
On this page
MentorAgent reads your classes at startup and decides which methods become actions: the methods that the model may call. The same rules decide six more things about each action: what it is called, which agent it belongs to, whether it is on, when it asks for confirmation, who may run it, and where it is published. This page gives the rules of the actions that your classes declare, each with its name. The areas that 1.4.0 adds, for actions registered in code (fluent), endpoints (endpoint), candidates (candidate), the actions of pages (page), teams from a source or a file (team) and skill sources (skill), are in ACTION-RULES.md with their tests, and their notes are in MentorAgent 1.4.0.
The rules are those of ACTION-RULES.md in the MentorAgent repository (external site). Each rule has a name that never changes and at least one test in the library that fails if the library stops following it. A rule that comes in, changes or is retired is named in the release notes of its version, and a retired name is never used again. The rules on this page are those of MentorAgent 1.4.0.
Which methods become actions
Section titled “Which methods become actions”public class TicketService
{
// An action: public, instance, declared here, with [MentorAction]
// (scan.marker). The tool is close_ticket (name.snake-case)
[MentorAction(Description = "Closes a support ticket",
RequiresConfirmation = true)]
public Task<string> CloseTicketAsync(string ticket) =>
Task.FromResult($"Ticket {ticket} closed.");
// An action too: a [Description] with a text, and no rules
[Description("Gets the status of a support ticket")]
public string GetTicketStatus(string ticket) => "Open";
// Not actions: static, private, or with no marker
[MentorAction(Description = "Never an action: static")]
public static string Count() => "3";
[MentorAction(Description = "Never an action: private")]
private string Purge() => "Purged.";
public string Format(string ticket) => $"#{ticket}";
// Off until a governor turns it on (enabled.off-by-default)
[MentorAction(Description = "Archives a ticket", Enabled = false,
RequiresConfirmation = true)]
public string ArchiveTicket(string ticket) => $"Ticket {ticket} archived.";
}
public class SupportTicketService : TicketService
{
// Not an action here: GetTicketStatus is inherited, so it is
// an action of TicketService only (scan.public-instance-declared)
}| Rule | What it says |
|---|---|
scan.assemblies-once | Each assembly in ScanAssemblies is read once. An assembly listed twice is read once, with a warning that names it. |
scan.concrete-classes | Only classes that are not abstract are read. Abstract classes, structs and interfaces give no action. |
scan.public-instance-declared | Only public instance methods declared on the class itself become actions. Static, internal, protected and private methods do not. A method that the class inherits is an action of its base class only. |
scan.marker | A method becomes an action with [MentorAction], whatever its description, or with a [Description] whose text is not blank. With neither, it is not an action. |
scan.mentor-action-wins | On a method with both [MentorAction] and [Description], [MentorAction] decides: its description, its confirmation and its roles. |
scan.override-keeps-action | An override of an action is an action of the class that overrides it, with what the base method declares. Class attributes such as [MentorAgent], [MentorTeam] and [MentorPage] do not pass to a derived class. |
scan.controllers-are-endpoints | Since 1.4.0, a controller is not read: a class that derives from ControllerBase, or carries [Controller] or [ApiController], and not [NonController]. A [MentorAction] on a controller's action is read from its endpoint, with AddMentorAgentServer(), where its authorization and filters run. Up to 1.3.1, the action called the method on an instance from the container. |
scan.attributes-not-created | Since 1.4.0, the scan creates none of your attributes: it reads which classes are controllers from the metadata of their attributes, so an attribute whose constructor throws does not stop the application. A class whose attributes name a type that does not load is skipped, with a warning that names it. |
The class must also be registered in dependency injection: a method of a class that the container cannot create is left out, with a warning at every new conversation.
Which agent an action belongs to
Section titled “Which agent an action belongs to”| Rule | What it says |
|---|---|
kind.one-per-class | A class has one kind only. MentorAgent picks the first kind that applies, in this order: [MentorTeam], then [MentorAgent], then [MentorSkill], then a plain class. The methods of a plain class are the coordinator's actions. |
kind.page-is-separate | [MentorPage] records the page, and does not change the kind of the class. Its methods follow the other rules. |
kind.agent-owns-methods | The methods of a [MentorAgent] class are the actions of that specialist, not the coordinator's. |
kind.skill-methods-level1 | The methods of a [MentorSkill] class are the coordinator's actions, registered once. A skill with no methods gives none. |
kind.team-needs-members | A [MentorTeam] class with no [TeamMember] property is left out, with a warning. |
kind.member-tools-leave-level1 | A class listed in [TeamMember(Tools = …)] is that member's toolbox. Its methods are not the coordinator's actions, and neither the Model Context Protocol (MCP) server nor the Agent-to-Agent (A2A) card publishes them. A [MentorSkill] class keeps its methods as the coordinator's actions. |
kind.member-tools-same-rules | A member's tool classes follow the scan.* rules, and each tool keeps what its attribute declares. |
The levels are explained in The three agent levels.
The names that the model sees
Section titled “The names that the model sees”| Rule | What it says |
|---|---|
name.snake-case | An action is named after its method. A trailing Async, with this exact case, is dropped. Then the name becomes snake case: every capital letter starts a new word, spaces and dashes become underscores, and digits stay. |
name.team-tool | A team is offered to the coordinator as one tool, named after the team's Name by the same rule. |
name.shared-warned | Two methods with the same action name, compared without regard to case, are named in a warning at startup. One method found twice is not two. |
name.called-method-decides | When methods share a name, the roles, the confirmation, its text and the page to open are those of the method that the call runs. |
| Method or team | Tool name |
|---|---|
CloseCaseAsync | close_case |
GetHTTPStatus | get_h_t_t_p_status |
Export2Csv | export2_csv |
A team named Business Analysis Team | business_analysis_team |
Options that name tools, such as RequiresApproval and IsReadOnlyAction, use these names. A name shared by two methods is in Common errors.
Whether an action is on
Section titled “Whether an action is on”| Rule | What it says |
|---|---|
enabled.off-by-default | An action declared [MentorAction(Enabled = false)] is in the catalog, with EnabledByDefault set to false, and nowhere else. It is offered to no agent, described to no model, and not published on the MCP server or on the A2A card. A call to it does not run, until an IMentorActionGovernor turns it on. |
enabled.external-decides | With an IMentorActionGovernor registered, its answer turns an action on or off, and null keeps what the code says. MentorAgent asks the governor when a session builds its tools, on every tools/list of the MCP server, and before every call. A session keeps the tools that it was built with, and MentorAgent refuses a call to an action that was turned off after that. A governor that throws, or does not answer in time, stops the action. An application can register only one governor. |
The governor is explained in Turn actions on and off from outside the code.
When an action asks for confirmation
Section titled “When an action asks for confirmation”A confirmation is asked only when RequireConfirmation is on and at least one source wants it: what the action declares, the default for writes, or RequiresApproval. With a governor, its answer takes the place of these sources.
| Rule | What it says |
|---|---|
confirm.declared-decides | An action whose attribute sets RequiresConfirmation to true or false gets what it declares. |
confirm.default-for-writes | A [MentorAction] that does not set RequiresConfirmation asks for confirmation when RequireConfirmationForWrites is on, which it is by default. It does not ask if the action only reads: ReadOnly = true, or IsReadOnlyAction says so. |
confirm.description-only-not-defaulted | A method marked with [Description] alone never asks for confirmation by default. The startup warning lists it among the writes that run without confirmation. |
confirm.predicate-adds | When RequiresApproval returns true for an action's name, the action asks for confirmation, and the predicate is asked again at every call. Returning false never takes away a confirmation that the action declares. The governor can take away both. |
confirm.master-switch | With RequireConfirmation off, no action of the application asks for confirmation, whatever it declares. The approval that a hosted MCP server asks for comes from the provider and is still shown. |
confirm.beats-read-only | An action that asks for confirmation is not read-only, whatever ReadOnly or IsReadOnlyAction say. |
confirm.unconfirmed-writes-warned | At startup a warning names the writes that run without confirmation, in two lists: the [MentorAction] methods that opt out, and the methods marked with [Description] alone. |
confirm.external-decides | With a governor, its answer decides whether a call is confirmed. Required asks even if the code does not. None does not ask even if the code does. Code keeps what the code says. A confirmation that the governor adds applies from the next call, and a confirmation that it takes away applies from the next session. The governor does not take away the Confirm of an action policy or the approval of a hosted MCP server. An action whose confirmation is taken away still counts as an action that changes data. |
What each declaration does on every channel is in the table Every declaration, on every channel.
Who may run an action
Section titled “Who may run an action”Roles and confirmation both apply, and roles come first: a user without the role is refused before anyone is asked to confirm.
| Rule | What it says |
|---|---|
roles.any-of | An action with RequiredRoles runs for a user who holds any one of them, checked with ClaimsPrincipal.IsInRole. Role names are case-sensitive. With no roles there is no check. |
roles.signed-in | An action with RequiredRoles needs a signed-in user. Without an AuthenticationStateProvider, or with nobody signed in, it is refused. |
roles.checked-before-confirmation | MentorAgent checks roles before the confirmation, so a user without the role is never asked to confirm. It checks the roles again when the confirmation comes back. Turning confirmations off does not turn the role check off. |
roles.offered-when-allowed | The model is offered only the actions that the user's roles allow, at every level. An action left out is still refused if it is called. |
roles.external-replace | With a governor, the roles that it gives an action replace the code's: null keeps the code's, and an empty list requires none. They decide what is offered, every call, and which MCP callers see and call the action. |
How the roles of your sign-in reach RequiredRoles is in Roles from your sign-in.
The description that the model reads
Section titled “The description that the model reads”| Rule | What it says |
|---|---|
describe.external-replace | With a governor, the description that it gives an action replaces the description in the code in everything that a model reads. This covers the tools of every agent, the texts that tool filtering ranks, and the tools/list of the MCP server. The action's name and arguments never change. What the user sees keeps the description in the code: the confirmation box and the bar of the running action. The A2A card, the catalog and the onboarding tour follow the code. |
Agents from definition files
Section titled “Agents from definition files”| Rule | What it says |
|---|---|
declarative.functions-match | A kind: function entry of a definition reaches its agent only if the session has an action of that name. A name that the application does not have, or an action that is off for the session, is taken away with a warning, and the agent loads without it. |
declarative.no-hosted-tools | A definition cannot add a tool of its own. webSearch, codeInterpreter, fileSearch and mcp entries are taken away with a warning, and the agent loads with the application's own tools. If they cannot be taken away, the agent is not loaded. |
Agents in YAML are explained in The three agent levels.
What is published to other applications
Section titled “What is published to other applications”| Rule | What it says |
|---|---|
surface.coordinator-only | The MCP server and the A2A card publish only the coordinator's actions, never a specialist's or a team member's. |
surface.mcp-withholds-gated | The MCP server does not publish an action that asks for confirmation, unless a governor takes the confirmation away. An action with roles is published only with McpCallerPrincipal, and only to the callers who hold one of its roles. An action that is off is not published, unless the governor turns it on. |
surface.card-ungated-only | The A2A card lists only the coordinator's actions that ask for no confirmation, need no role, and whose class the container can create. A name that two actions share is left off when either of them is gated. The card follows the code only. |
surface.governor-session | The governor is asked with the session's id on every channel, the same id that the gate's decisions carry. On the MCP server it is a fingerprint of the MCP session. |
The MCP server and the A2A server pages show how to publish your actions.
See also
Section titled “See also”- Roles, confirmation and governance — Role checks and human-in-the-loop approval for AI agent tools in .NET, enforced in code on every channel and not in the prompt, and what stays in your code.
- The three agent levels — Actions, specialists and teams: how the three levels of MentorAgent map to Agent Framework, and when to use each one.
- Attributes — The parameters of MentorAction, MentorAgent, MentorTeam, TeamMember, MentorPage, MentorSkill and MentorExclude, with their defaults and rules.
- Troubleshooting — Fix common problems with MentorAgent: startup errors, blocked requests, roles, confirmation, local models. And where to get help or report a bug.
