Class Tool

Namespace

ModelContextProtocol.Protocol

Assembly

ModelContextProtocol.Core.dll

Represents a tool that the server is capable of calling.

public sealed class Tool : IBaseMetadata

Inheritance

object

Tool

Implements

IBaseMetadata

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Properties

Annotations

Gets or sets optional additional tool information and behavior hints.

[JsonPropertyName("annotations")]
public ToolAnnotations? Annotations { get; set; }

Property Value

ToolAnnotations

Remarks

These annotations provide metadata about the tool's behavior, such as whether it's read-only, destructive, idempotent, or operates in an open world. They also can include a human-readable title. Note that these are hints and should not be relied upon for security decisions.

Description

Gets or sets a human-readable description of the tool.

[JsonPropertyName("description")]
public string? Description { get; set; }

Property Value

string

Remarks

This description helps the AI model understand what the tool does and when to use it. It should be clear, concise, and accurately describe the tool's purpose and functionality.

The description is typically presented to AI models to help them determine when and how to use the tool based on user requests. A well-written description significantly reduces incorrect tool invocations. Include information about what the tool does, any constraints or prerequisites, and what it returns.

Similarly, individual parameter descriptions (provided via DescriptionAttribute on tool method parameters) are important for guiding the model to supply correct argument values. Descriptions should document expected formats, valid value ranges, and any other constraints the model should be aware of.

Icons

Gets or sets an optional list of icons for this tool.

[JsonPropertyName("icons")]
public IList<Icon>? Icons { get; set; }

Property Value

IList<Icon>

Remarks

This can be used by clients to display the tool's icon in a user interface.

InputSchema

Gets or sets a JSON Schema object defining the expected parameters for the tool.

[JsonPropertyName("inputSchema")]
[JsonRequired]
public JsonElement InputSchema { get; set; }

Property Value

JsonElement

Remarks

The schema must be a valid JSON Schema object with the "type" property set to "object". This is enforced by validation in the setter which will throw an ArgumentException if an invalid schema is provided.

The schema typically defines the properties (parameters) that the tool accepts, their types, and which ones are required. This helps AI models understand how to structure their calls to the tool.

If not explicitly set, a default minimal schema of {"type":"object"} is used.

Exceptions

ArgumentException

The value is not a valid MCP tool JSON schema.

Meta

Gets or sets metadata reserved by MCP for protocol-level metadata.

[JsonPropertyName("_meta")]
public JsonObject? Meta { get; set; }

Property Value

JsonObject

Remarks

Implementations must not make assumptions about its contents.

Name

Gets or sets the unique identifier for this item.

[JsonPropertyName("name")]
public required string Name { get; set; }

Property Value

string

OutputSchema

Gets or sets a JSON Schema document describing the shape of the tool's structured output.

[JsonPropertyName("outputSchema")]
public JsonElement? OutputSchema { get; set; }

Property Value

JsonElement?

Remarks

Per SEP-2106 ("Allow valid JSON Schemas in outputSchema"), the schema may describe any JSON value — object, array, string, number, boolean, or null — to support tools whose structured output is not an object. The setter only checks that the supplied value is a structurally valid JSON Schema 2020-12 document (a JSON object, or the boolean schemas true/false per §4.3); deeper keyword-level validation is intentionally not performed.

The schema describes the shape of the value placed in StructuredContent. Unlike InputSchema, the top-level type is not required to be "object".

Exceptions

ArgumentException

The value is not a valid JSON Schema 2020-12 document — i.e., not a JSON object or a JSON boolean.

Title

Gets or sets a title.

[JsonPropertyName("title")]
public string? Title { get; set; }

Property Value

string

Remarks

This is intended for UI and end-user contexts. It is optimized to be human-readable and easily understood, even by those unfamiliar with domain-specific terminology. If not provided, Name can be used for display (except for tools, where Title, if present, should be given precedence over using Name).