Skip to main content

​
Definition

Assembly: Microsoft.OData.Mcp.Core.dll Namespace: Microsoft.OData.Mcp.Core.Tools Inheritance: System.Object

​
Syntax

Microsoft.OData.Mcp.Core.Tools.McpToolDefinition

​
Summary

Represents a complete MCP tool definition with metadata and implementation details.

​
Remarks

This class encapsulates all information needed to register and execute an MCP tool, including its schema, parameters, authorization requirements, and execution context.

​
Constructors

​
.ctor

Initializes a new instance of the McpToolDefinition class.

​
Syntax

public McpToolDefinition()

​
.ctor Inherited

Inherited from object

​
Syntax

public Object()

​
Properties

​
Category

Gets or sets the tool category.

​
Syntax

public required string Category { get; set; }

​
Property Value

Type: string The category that groups related tools together.

​
Remarks

Common categories include “CRUD”, “Query”, “Navigation”, and “Batch”. Categories help organize tools and can be used for filtering and authorization.

​
CreatedAt

Gets or sets the time when this tool definition was created.

​
Syntax

public System.DateTime CreatedAt { get; set; }

​
Property Value

Type: System.DateTime The UTC timestamp when the tool was generated.

​
Remarks

This timestamp is used for caching, versioning, and audit purposes.

​
DeprecationMessage

Gets or sets the deprecation message for deprecated tools.

​
Syntax

public string DeprecationMessage { get; set; }

​
Property Value

Type: string? A message explaining why the tool is deprecated and what should be used instead.

​
Remarks

This message is shown to users when they attempt to use a deprecated tool, guiding them to better alternatives.

​
Description

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

​
Syntax

public required string Description { get; set; }

​
Property Value

Type: string A description explaining what the tool does and how to use it.

​
Remarks

This description is used by AI models to understand the tool’s purpose and determine when it should be used.

​
Examples

Gets or sets example usage scenarios for the tool.

​
Syntax

public System.Collections.Generic.List<Microsoft.OData.Mcp.Core.Tools.McpToolExample> Examples { get; set; }

​
Property Value

Type: System.Collections.Generic.List<Microsoft.OData.Mcp.Core.Tools.McpToolExample> A collection of example usage patterns.

​
Remarks

Examples help AI models understand how to use the tool effectively and provide better assistance to users.

​
Handler

Gets or sets the tool implementation handler.

​
Syntax

public required System.Func<Microsoft.OData.Mcp.Core.Tools.McpToolContext, System.Text.Json.JsonDocument, System.Threading.Tasks.Task<Microsoft.OData.Mcp.Core.Tools.McpToolResult>> Handler { get; set; }

​
Property Value

Type: System.Func<Microsoft.OData.Mcp.Core.Tools.McpToolContext, System.Text.Json.JsonDocument, System.Threading.Tasks.Task<Microsoft.OData.Mcp.Core.Tools.McpToolResult>> The function that executes the tool logic.

​
Remarks

This is the actual implementation that gets called when the tool is invoked. It receives the tool context and parameters, and returns the execution result.

​
InputSchema

Gets or sets the input schema for the tool parameters.

​
Syntax

public required System.Text.Json.JsonDocument InputSchema { get; set; }

​
Property Value

Type: System.Text.Json.JsonDocument A JSON schema document defining the tool’s input parameters.

​
Remarks

This schema is used by MCP clients to validate input and provide type-safe parameter binding. It should follow JSON Schema specification.

​
IsDeprecated

Gets or sets a value indicating whether this tool is deprecated.

​
Syntax

public bool IsDeprecated { get; set; }

​
Property Value

Type: bool true if the tool is deprecated; otherwise, false.

​
Remarks

Deprecated tools are still functional but should be avoided in favor of newer alternatives. They may be removed in future versions.

​
Metadata

Gets or sets additional metadata for the tool.

​
Syntax

public System.Collections.Generic.Dictionary<string, object> Metadata { get; set; }

​
Property Value

Type: System.Collections.Generic.Dictionary<string, object> A dictionary of custom metadata key-value pairs.

​
Remarks

This can include information such as rate limits, caching behavior, or other tool-specific configuration data.

​
Name

Gets or sets the unique name of the tool.

​
Syntax

public required string Name { get; set; }

​
Property Value

Type: string The tool name as it will appear in the MCP protocol.

​
Remarks

Tool names must be unique within the MCP server and should follow naming conventions that clearly indicate their purpose and target entity.

​
OperationType

Gets or sets the operation type for this tool.

​
Syntax

public Microsoft.OData.Mcp.Core.Tools.McpToolOperationType OperationType { get; set; }

​
Property Value

Type: Microsoft.OData.Mcp.Core.Tools.McpToolOperationType The type of operation this tool performs.

​
Remarks

Operation types are used for authorization and auditing. They indicate the level of data access and modification the tool performs.

​
OutputSchema

Gets or sets the output schema for the tool results.

​
Syntax

public System.Text.Json.JsonDocument OutputSchema { get; set; }

​
Property Value

Type: System.Text.Json.JsonDocument? A JSON schema document defining the tool’s output format.

​
Remarks

This schema describes the structure of the tool’s return value, helping clients understand and process the results.

​
RequiredRoles

Gets or sets the required roles for this tool.

​
Syntax

public System.Collections.Generic.List<string> RequiredRoles { get; set; }

​
Property Value

Type: System.Collections.Generic.List<string> A collection of roles that users must have to use this tool.

​
Remarks

This provides role-based authorization control in addition to or instead of scope-based authorization.

​
RequiredScopes

Gets or sets the required OAuth2 scopes for this tool.

​
Syntax

public System.Collections.Generic.List<string> RequiredScopes { get; set; }

​
Property Value

Type: System.Collections.Generic.List<string> A collection of OAuth2 scopes that users must have to use this tool.

​
Remarks

Users must have at least one of these scopes to execute the tool. This provides fine-grained authorization control based on OAuth2 tokens.

​
SupportsBatch

Gets or sets a value indicating whether this tool supports batch operations.

​
Syntax

public bool SupportsBatch { get; set; }

​
Property Value

Type: bool true if the tool can process multiple items in a single call; otherwise, false.

​
Remarks

Batch-enabled tools can improve performance by processing multiple operations in a single request to the underlying OData service.

​
TargetEntitySet

Gets or sets the target entity set for entity set-specific tools.

​
Syntax

public string TargetEntitySet { get; set; }

​
Property Value

Type: string? The name of the target entity set, or null for entity type tools.

​
Remarks

This is used for tools that operate on specific entity sets, which may have different permissions or configurations than the entity type.

​
TargetEntityType

Gets or sets the target entity type for entity-specific tools.

​
Syntax

public string TargetEntityType { get; set; }

​
Property Value

Type: string? The fully qualified name of the target entity type, or null for general tools.

​
Remarks

This is used for entity-specific tools to identify which OData entity type the tool operates on. General tools that work across entities should leave this null.

​
Version

Gets or sets the version of the tool.

​
Syntax

public string Version { get; set; }

​
Property Value

Type: string The version string for this tool definition.

​
Remarks

Tool versions help track changes and ensure compatibility. They should follow semantic versioning principles.

​
Methods

​
AddExample

Adds an example to the tool definition.

​
Syntax

public void AddExample(string title, string description, System.Text.Json.JsonDocument input, System.Text.Json.JsonDocument expectedOutput = null)

​
Parameters

NameTypeDescription
titlestringThe example title.
descriptionstringThe example description.
inputSystem.Text.Json.JsonDocumentThe example input parameters.
expectedOutputSystem.Text.Json.JsonDocument?The expected output (optional).

​
Exceptions

ExceptionDescription
ArgumentExceptionThrown when title is null or whitespace.
ArgumentNullExceptionThrown when input is null.

​
AddMetadata

Adds metadata to the tool definition.

​
Syntax

public void AddMetadata(string key, object value)

​
Parameters

NameTypeDescription
keystringThe metadata key.
valueobjectThe metadata value.

​
Exceptions

ExceptionDescription
ArgumentExceptionThrown when key is null or whitespace.

​
CreateCrudTool

Creates a basic CRUD tool definition.

​
Syntax

public static Microsoft.OData.Mcp.Core.Tools.McpToolDefinition CreateCrudTool(string name, string description, Microsoft.OData.Mcp.Core.Tools.McpToolOperationType operationType, string entityType, System.Text.Json.JsonDocument inputSchema, System.Func<Microsoft.OData.Mcp.Core.Tools.McpToolContext, System.Text.Json.JsonDocument, System.Threading.Tasks.Task<Microsoft.OData.Mcp.Core.Tools.McpToolResult>> handler, string entitySet = null)

​
Parameters

NameTypeDescription
namestringThe tool name.
descriptionstringThe tool description.
operationTypeMicrosoft.OData.Mcp.Core.Tools.McpToolOperationTypeThe operation type.
entityTypestringThe target entity type.
inputSchemaSystem.Text.Json.JsonDocumentThe input schema.
handlerSystem.Func<Microsoft.OData.Mcp.Core.Tools.McpToolContext, System.Text.Json.JsonDocument, System.Threading.Tasks.Task<Microsoft.OData.Mcp.Core.Tools.McpToolResult>>The tool handler.
entitySetstring?The optional entity set name for the entity type.

​
Returns

Type: Microsoft.OData.Mcp.Core.Tools.McpToolDefinition A new tool definition for CRUD operations.

​
Exceptions

ExceptionDescription
ArgumentExceptionThrown when required parameters are null or empty.
ArgumentNullExceptionThrown when inputSchema or handler is null.

​
CreateQueryTool

Creates a query tool definition.

​
Syntax

public static Microsoft.OData.Mcp.Core.Tools.McpToolDefinition CreateQueryTool(string name, string description, System.Text.Json.JsonDocument inputSchema, System.Func<Microsoft.OData.Mcp.Core.Tools.McpToolContext, System.Text.Json.JsonDocument, System.Threading.Tasks.Task<Microsoft.OData.Mcp.Core.Tools.McpToolResult>> handler)

​
Parameters

NameTypeDescription
namestringThe tool name.
descriptionstringThe tool description.
inputSchemaSystem.Text.Json.JsonDocumentThe input schema.
handlerSystem.Func<Microsoft.OData.Mcp.Core.Tools.McpToolContext, System.Text.Json.JsonDocument, System.Threading.Tasks.Task<Microsoft.OData.Mcp.Core.Tools.McpToolResult>>The tool handler.

​
Returns

Type: Microsoft.OData.Mcp.Core.Tools.McpToolDefinition A new tool definition for query operations.

​
Exceptions

ExceptionDescription
ArgumentExceptionThrown when required parameters are null or empty.
ArgumentNullExceptionThrown when inputSchema or handler is null.

​
Equals Inherited Virtual

Inherited from object

​
Syntax

public virtual bool Equals(object obj)

​
Parameters

NameTypeDescription
objobject?-

​
Returns

Type: bool

​
Equals Inherited

Inherited from object

​
Syntax

public static bool Equals(object objA, object objB)

​
Parameters

NameTypeDescription
objAobject?-
objBobject?-

​
Returns

Type: bool

​
GetHashCode Inherited Virtual

Inherited from object

​
Syntax

public virtual int GetHashCode()

​
Returns

Type: int

​
GetMetadata

Gets metadata value by key.

​
Syntax

public T GetMetadata<T>(string key)

​
Parameters

NameTypeDescription
keystringThe metadata key.

​
Returns

Type: T? The metadata value if found and of the correct type; otherwise, the default value.

​
Type Parameters

  • T - The type of the metadata value.

​
GetType Inherited

Inherited from object

​
Syntax

public System.Type GetType()

​
Returns

Type: System.Type

​
IsAuthorizedForUser

Determines whether the tool is authorized for the specified user context.

​
Syntax

public bool IsAuthorizedForUser(System.Collections.Generic.IEnumerable<string> userScopes, System.Collections.Generic.IEnumerable<string> userRoles)

​
Parameters

NameTypeDescription
userScopesSystem.Collections.Generic.IEnumerable<string>The user’s OAuth2 scopes.
userRolesSystem.Collections.Generic.IEnumerable<string>The user’s roles.

​
Returns

Type: bool true if the user is authorized to use this tool; otherwise, false.

​
MemberwiseClone Inherited

Inherited from object

​
Syntax

protected internal object MemberwiseClone()

​
Returns

Type: object

​
ReferenceEquals Inherited

Inherited from object

​
Syntax

public static bool ReferenceEquals(object objA, object objB)

​
Parameters

NameTypeDescription
objAobject?-
objBobject?-

​
Returns

Type: bool

​
ToString Override

Returns a string representation of the tool definition.

​
Syntax

public override string ToString()

​
Returns

Type: string A summary of the tool definition.

​
ToString Inherited Virtual

Inherited from object

​
Syntax

public virtual string ToString()

​
Returns

Type: string?

​
Validate

Validates the tool definition for completeness and correctness.

​
Syntax

public System.Collections.Generic.IEnumerable<string> Validate()

​
Returns

Type: System.Collections.Generic.IEnumerable<string> A collection of validation errors, or empty if the tool is valid.