Preamble

• SEP Number: TBD
• Title: Add agencyHint tool annotation
• Authors: Rajesh Kamisetty
• Status: Proposal

Abstract

The proposal introduces a new boolean tool annotation agencyHint within the Model Context Protocol (MCP) ToolAnnotations interface. The annotation is intended to indicate whether a tool possesses agentic capabilities—meaning it encapsulates reasoning, planning, or autonomous decision-making behavior rather than simply invoking a single atomic action. This hint will assist clients in presenting and managing agentic tools appropriately.

Note: This proposal was written by primarily with the help of ChatGPT - specifically by pointing Atlas to the https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations and instructing it to create the issue based on the community standards.

Motivation

The current set of tool annotations (such as destructiveHint, idempotentHint, openWorldHint, readOnlyHint, and taskHint) communicate important safety and UX characteristics, but none explicitly convey whether a tool itself is an agent that can perform multi-step reasoning and planning. As agentic tooling becomes more prevalent, distinguishing between simple procedural tools and those that embed goal-driven autonomy will help clients implement effective human-in-the-loop confirmation flows and user interfaces. For example, a tool that orchestrates a long-running process with multiple sub-operations may warrant additional confirmation or monitoring compared to a single API call. A dedicated agencyHint will provide this context to clients and maintainers without affecting the model context.

Specification

Extend the ToolAnnotations interface with an optional agencyHint boolean field:

interface ToolAnnotations {
  destructiveHint?: boolean;
  idempotentHint?: boolean;
  openWorldHint?: boolean;
  readOnlyHint?: boolean;
  taskHint?: “never” | “optional” | “always”;
  agencyHint?: boolean; // NEW: Indicates whether the tool exhibits agentic behavior (reasoning, planning, multi-step 
  title?: string;
execution)
}

When present and set to true, this hint signals that the tool may perform reasoning, planning, or multi-step operations toward reaching goals with autonomy. A default value of false should be assumed when the annotation is omitted.

Rationale and Discussion

• Clarity for clients: Agentic tools may require different UX flows (e.g., confirmation or progressive disclosure of actions) than simple single-step tools. This hint allows clients to adapt.
• Interoperability: The hint is purely advisory and does not enforce behavior, so it should not break backward compatibility.
• Optional: As with other hints, tool authors may omit the annotation. Clients should treat absence as false.
• Comparisons: This hint complements, but does not replace, existing hints like destructiveHint or openWorldHint.

Backwards Compatibility

The addition of an optional agencyHint field is non-breaking and does not affect existing tools. Tools that do not define the hint will continue to function as before.

Implementation

If accepted, the specification documentation should be updated to include the new agencyHint annotation in the ToolAnnotations interface and to describe its semantics. Example code and guidelines for servers and clients should also be updated to reference the hint.

11/16 - Minor edit to reflect latest draft (2025-11-25 version)