88 lines
3.9 KiB
C#
88 lines
3.9 KiB
C#
using System.Diagnostics.CodeAnalysis;
|
|
using System.Text.Json.Nodes;
|
|
using System.Text.Json.Serialization;
|
|
|
|
namespace ModelContextProtocol.Protocol;
|
|
|
|
/// <summary>
|
|
/// Represents the result of a <see cref="RequestMethods.ToolsCall"/> request from a client to invoke a tool provided by the server.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>
|
|
/// Tool execution errors (including input validation errors, API failures, and business logic errors)
|
|
/// should be reported inside the result object with <see cref="IsError"/> set to <see langword="true"/>,
|
|
/// rather than as a <see cref="JsonRpcError"/>. This allows language models to see error details
|
|
/// and potentially self-correct in subsequent requests.
|
|
/// </para>
|
|
/// <para>
|
|
/// To return a validation or business-logic error from a tool method, either throw an <see cref="McpException"/>
|
|
/// (whose <see cref="Exception.Message"/> will be included in the error result), or declare the tool's return type
|
|
/// as <see cref="CallToolResult"/> so it can be returned directly with <see cref="IsError"/> set to <see langword="true"/>
|
|
/// and details in <see cref="Content"/>. Using <see cref="CallToolResult"/> as the return type gives the tool full control
|
|
/// over both success and error responses.
|
|
/// </para>
|
|
/// <para>
|
|
/// Protocol-level errors (such as unknown tool names, malformed requests that fail schema validation,
|
|
/// or server errors) should be reported as MCP protocol error responses using <see cref="McpErrorCode"/>.
|
|
/// </para>
|
|
/// <para>
|
|
/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
|
|
/// </para>
|
|
/// </remarks>
|
|
public sealed class CallToolResult : Result
|
|
{
|
|
/// <summary>
|
|
/// Gets or sets the response content from the tool call.
|
|
/// </summary>
|
|
[JsonPropertyName("content")]
|
|
public IList<ContentBlock> Content { get; set; } = [];
|
|
|
|
/// <summary>
|
|
/// Gets or sets an optional JSON object representing the structured result of the tool call.
|
|
/// </summary>
|
|
[JsonPropertyName("structuredContent")]
|
|
public JsonNode? StructuredContent { get; set; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets a value that indicates whether the tool call was unsuccessful.
|
|
/// </summary>
|
|
/// <value>
|
|
/// <see langword="true"/> to signify that the tool execution failed; <see langword="false"/> if it was successful.
|
|
/// </value>
|
|
/// <remarks>
|
|
/// <para>
|
|
/// Tool execution errors (including input validation errors, API failures, and business logic errors)
|
|
/// are reported with this property set to <see langword="true"/> and details in the <see cref="Content"/>
|
|
/// property, rather than as protocol-level errors.
|
|
/// </para>
|
|
/// <para>
|
|
/// This design allows language models to receive detailed error feedback and potentially self-correct
|
|
/// in subsequent requests. For example, if a date parameter is in the wrong format or out of range,
|
|
/// the error message in <see cref="Content"/> can explain the issue, enabling the model to retry
|
|
/// with corrected parameters.
|
|
/// </para>
|
|
/// </remarks>
|
|
[JsonPropertyName("isError")]
|
|
public bool? IsError { get; set; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets the task data for the newly created task.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// This property is populated only for task-augmented tool calls. When present, the other properties
|
|
/// (<see cref="Content"/>, <see cref="StructuredContent"/>, <see cref="IsError"/>) may not be populated.
|
|
/// The actual tool result can be retrieved later via <c>tasks/result</c>.
|
|
/// </remarks>
|
|
[Experimental(Experimentals.Tasks_DiagnosticId, UrlFormat = Experimentals.Tasks_Url)]
|
|
[JsonIgnore]
|
|
public McpTask? Task
|
|
{
|
|
get => TaskCore;
|
|
set => TaskCore = value;
|
|
}
|
|
|
|
// See ExperimentalInternalPropertyTests.cs before modifying this property.
|
|
[JsonInclude]
|
|
[JsonPropertyName("task")]
|
|
internal McpTask? TaskCore { get; set; }
|
|
}
|