Definition
Assembly: Microsoft.OData.Mcp.Core.dll Namespace: Microsoft.OData.Mcp.Core.Tools Inheritance: System.ObjectSyntax
Summary
Represents an example usage pattern for an MCP tool.Remarks
Examples help AI models understand how to use tools effectively and provide better assistance to users by demonstrating common usage patterns.Constructors
.ctor
Initializes a new instance of the McpToolExample class.Syntax
.ctor
Initializes a new instance of the McpToolExample class with basic information.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
title | string | The example title. |
input | System.Text.Json.JsonDocument | The example input parameters. |
Exceptions
| Exception | Description |
|---|---|
ArgumentException | Thrown when title is null or whitespace. |
ArgumentNullException | Thrown when input is null. |
.ctor Inherited
Inherited from
objectSyntax
Properties
Category
Gets or sets the scenario category for this example.Syntax
Property Value
Type:string
The category that groups related examples together.
Remarks
Common categories include “Basic Usage”, “Advanced Queries”, “Error Handling”, “Performance Optimization”, etc. This helps organize examples by complexity or purpose.Description
Gets or sets the description of the example.Syntax
Property Value
Type:string
A detailed description explaining the example’s purpose and context.
Remarks
The description should provide context about when and why this example would be useful, including any prerequisites or assumptions.Difficulty
Gets or sets the difficulty level of this example.Syntax
Property Value
Type:Microsoft.OData.Mcp.Core.Tools.McpToolExampleDifficulty
The complexity level of the example.
Remarks
Difficulty levels help users and AI models choose appropriate examples based on their experience and needs.ExpectedExecutionTime
Gets or sets the expected execution time for this example.Syntax
Property Value
Type:System.Nullable<System.TimeSpan>
The approximate time this example should take to execute.
Remarks
This helps set expectations and can be used for performance monitoring and timeout configuration.ExpectedOutput
Gets or sets the expected output for this example.Syntax
Property Value
Type:System.Text.Json.JsonDocument?
A JSON document showing the expected result, or null if not provided.
Remarks
Expected output helps users understand what to expect from the tool and can be used for testing and validation purposes.Input
Gets or sets the example input parameters.Syntax
Property Value
Type:System.Text.Json.JsonDocument
A JSON document containing the example input parameters.
Remarks
The input should be a complete, valid example that demonstrates the tool’s parameter schema and typical usage patterns.Notes
Gets or sets additional notes about this example.Syntax
Property Value
Type:string?
Free-form notes providing additional context or warnings.
Remarks
Notes can include tips, warnings about edge cases, performance considerations, or links to related documentation.Prerequisites
Gets or sets the prerequisites for this example.Syntax
Property Value
Type:System.Collections.Generic.List<string>
A list of conditions that must be met for this example to work.
Remarks
Prerequisites might include required permissions, data setup, configuration settings, or other dependencies.RequiresAuthentication
Gets or sets a value indicating whether this example requires authentication.Syntax
Property Value
Type:bool
true if authentication is required; otherwise, false.
Remarks
This flag helps users and AI models understand whether they need to provide authentication credentials to use this example.Tags
Gets or sets the tags associated with this example.Syntax
Property Value
Type:System.Collections.Generic.List<string>
A collection of tags for categorizing and searching examples.
Remarks
Tags provide flexible categorization beyond the main category, allowing for cross-cutting concerns like “authentication”, “pagination”, “bulk-operations”, etc.Title
Gets or sets the title of the example.Syntax
Property Value
Type:string
A brief, descriptive title for the example.
Remarks
The title should clearly indicate what the example demonstrates, such as “Create a new customer” or “Query products by category”.Methods
AddPrerequisite
Adds a prerequisite to this example.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
prerequisite | string | The prerequisite to add. |
Exceptions
| Exception | Description |
|---|---|
ArgumentException | Thrown when prerequisite is null or whitespace. |
AddTag
Adds a tag to this example.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
tag | string | The tag to add. |
Exceptions
| Exception | Description |
|---|---|
ArgumentException | Thrown when tag is null or whitespace. |
AddTags
Adds multiple tags to this example.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
tags | string[] | The tags to add. |
Exceptions
| Exception | Description |
|---|---|
ArgumentNullException | Thrown when tags is null. |
Clone
Creates a deep copy of this example.Syntax
Returns
Type:Microsoft.OData.Mcp.Core.Tools.McpToolExample
A new instance that is a copy of this example.
Create
Creates a basic example with the specified title and input.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
title | string | The example title. |
input | object | The input object to serialize to JSON. |
description | string? | Optional description of the example. |
Returns
Type:Microsoft.OData.Mcp.Core.Tools.McpToolExample
A new tool example.
Exceptions
| Exception | Description |
|---|---|
ArgumentException | Thrown when title is null or whitespace. |
ArgumentNullException | Thrown when input is null. |
CreateWithOutput
Creates an example with expected output.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
title | string | The example title. |
input | object | The input object to serialize to JSON. |
expectedOutput | object | The expected output object to serialize to JSON. |
description | string? | Optional description of the example. |
Returns
Type:Microsoft.OData.Mcp.Core.Tools.McpToolExample
A new tool example with expected output.
Exceptions
| Exception | Description |
|---|---|
ArgumentException | Thrown when title is null or whitespace. |
ArgumentNullException | Thrown when input or expectedOutput is null. |
Equals Inherited Virtual
Inherited from
objectSyntax
Parameters
| Name | Type | Description |
|---|---|---|
obj | object? | - |
Returns
Type:bool
Equals Inherited
Inherited from
objectSyntax
Parameters
| Name | Type | Description |
|---|---|---|
objA | object? | - |
objB | object? | - |
Returns
Type:bool
GetExpectedOutputJson
Gets the expected output as a formatted JSON string.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
indent | bool | Whether to indent the JSON for readability. |
Returns
Type:string?
The expected output as a JSON string, or null if no expected output is defined.
GetHashCode Inherited Virtual
Inherited from
objectSyntax
Returns
Type:int
GetInputJson
Gets the input as a formatted JSON string.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
indent | bool | Whether to indent the JSON for readability. |
Returns
Type:string
The input parameters as a JSON string.
GetType Inherited
Inherited from
objectSyntax
Returns
Type:System.Type
HasTag
Determines whether this example has the specified tag.Syntax
Parameters
| Name | Type | Description |
|---|---|---|
tag | string | The tag to check for. |
Returns
Type:bool
true if the example has the specified tag; otherwise, false.
MemberwiseClone Inherited
Inherited from
objectSyntax
Returns
Type:object
ReferenceEquals Inherited
Inherited from
objectSyntax
Parameters
| Name | Type | Description |
|---|---|---|
objA | object? | - |
objB | object? | - |
Returns
Type:bool
ToString Override
Returns a string representation of the example.Syntax
Returns
Type:string
A summary of the example.
ToString Inherited Virtual
Inherited from
objectSyntax
Returns
Type:string?
Validate
Validates the example for completeness and correctness.Syntax
Returns
Type:System.Collections.Generic.IEnumerable<string>
A collection of validation errors, or empty if the example is valid.