McpToolDefinition

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

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

Name	Type	Description
`title`	`string`	The example title.
`description`	`string`	The example description.
`input`	`System.Text.Json.JsonDocument`	The example input parameters.
`expectedOutput`	`System.Text.Json.JsonDocument?`	The expected output (optional).

Exceptions

Exception	Description
`ArgumentException`	Thrown when title is null or whitespace.
`ArgumentNullException`	Thrown when input is null.

AddMetadata

Adds metadata to the tool definition.

Syntax

public void AddMetadata(string key, object value)

Parameters

Name	Type	Description
`key`	`string`	The metadata key.
`value`	`object`	The metadata value.

Exceptions

Exception	Description
`ArgumentException`	Thrown 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

Name	Type	Description
`name`	`string`	The tool name.
`description`	`string`	The tool description.
`operationType`	`Microsoft.OData.Mcp.Core.Tools.McpToolOperationType`	The operation type.
`entityType`	`string`	The target entity type.
`inputSchema`	`System.Text.Json.JsonDocument`	The input schema.
`handler`	`System.Func<Microsoft.OData.Mcp.Core.Tools.McpToolContext, System.Text.Json.JsonDocument, System.Threading.Tasks.Task<Microsoft.OData.Mcp.Core.Tools.McpToolResult>>`	The tool handler.
`entitySet`	`string?`	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

Exception	Description
`ArgumentException`	Thrown when required parameters are null or empty.
`ArgumentNullException`	Thrown 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

Name	Type	Description
`name`	`string`	The tool name.
`description`	`string`	The tool description.
`inputSchema`	`System.Text.Json.JsonDocument`	The input schema.
`handler`	`System.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

Exception	Description
`ArgumentException`	Thrown when required parameters are null or empty.
`ArgumentNullException`	Thrown when inputSchema or handler is null.

Equals Inherited Virtual

Inherited from object

Syntax

public virtual bool Equals(object obj)

Parameters

Name	Type	Description
`obj`	`object?`	-

Returns

Type: bool

Equals Inherited

Inherited from object

Syntax

public static bool Equals(object objA, object objB)

Parameters

Name	Type	Description
`objA`	`object?`	-
`objB`	`object?`	-

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

Name	Type	Description
`key`	`string`	The 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

Name	Type	Description
`userScopes`	`System.Collections.Generic.IEnumerable<string>`	The user’s OAuth2 scopes.
`userRoles`	`System.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

Name	Type	Description
`objA`	`object?`	-
`objB`	`object?`	-

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.

​Definition

​Syntax

​Summary

​Remarks

​Constructors

​ .ctor

​Syntax

​ .ctor Inherited

​Syntax

​Properties

​ Category

​Syntax

​Property Value

​Remarks

​ CreatedAt

​Syntax

​Property Value

​Remarks

​ DeprecationMessage

​Syntax

​Property Value

​Remarks

​ Description

​Syntax

​Property Value

​Remarks

​ Examples

​Syntax

​Property Value

​Remarks

​ Handler

​Syntax

​Property Value

​Remarks

​ InputSchema

​Syntax

​Property Value

​Remarks

​ IsDeprecated

​Syntax

​Property Value

​Remarks

​ Metadata

​Syntax

​Property Value

​Remarks

​ Name

​Syntax

​Property Value

​Remarks

​ OperationType

​Syntax

​Property Value

​Remarks

​ OutputSchema

​Syntax

​Property Value

​Remarks

​ RequiredRoles

​Syntax

​Property Value

​Remarks

​ RequiredScopes

​Syntax

​Property Value

​Remarks

​ SupportsBatch

​Syntax

​Property Value

​Remarks

​ TargetEntitySet

​Syntax

​Property Value

​Remarks

​ TargetEntityType

​Syntax

​Property Value

​Remarks

​ Version

​Syntax

Definition

Syntax

Summary

Remarks

Constructors

.ctor

Syntax

.ctor Inherited

Syntax

Properties

Category

Syntax

Property Value

Remarks

CreatedAt

Syntax

Property Value

Remarks

DeprecationMessage

Syntax

Property Value

Remarks

Description

Syntax

Property Value

Remarks

Examples

Syntax

Property Value

Remarks

Handler

Syntax

Property Value

Remarks

InputSchema

Syntax

Property Value

Remarks

IsDeprecated

Syntax

Property Value

Remarks

Metadata

Syntax

Property Value

Remarks

Name

Syntax

Property Value

Remarks

OperationType

Syntax

Property Value

Remarks

OutputSchema

Syntax

Property Value

Remarks

RequiredRoles

Syntax

Property Value

Remarks

RequiredScopes

Syntax

Property Value

Remarks

SupportsBatch

Syntax

Property Value

Remarks

TargetEntitySet

Syntax

Property Value

Remarks

TargetEntityType

Syntax

Property Value

Remarks

Version

Syntax