Package dev.tachyonmcp.api.server.features.tools

Interface ToolResult

All Known Implementing Classes:
ToolResult.Deferred, ToolResult.Error, ToolResult.InputRequired, ToolResult.Success, ToolResult.WithMeta
public sealed interface ToolResult permits ToolResult.Success, ToolResult.Error, ToolResult.WithMeta, ToolResult.InputRequired, ToolResult.Deferred
Outcome of a tool invocation: success, error, input-required, or deferred.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    ToolResult.Deferred
    Sentinel returned by a task-augmented handler that defers completion to the caller.
    static final record 
    ToolResult.Error
    A failed invocation carrying a human-readable error message.
    static final record 
    ToolResult.InputRequired
    Signals that completing the tool call requires additional input from the caller.
    static final record 
    ToolResult.Success
    A successful invocation, carrying an optional structured value and its content blocks.
    static final record 
    ToolResult.WithMeta
    Wraps another result with request-level _meta entries.

  • Method Summary

    Modifier and Type
    Method
    Description
    static ToolResult
    blocks(ContentBlock... blocks)
    Deprecated, for removal: This API element is subject to removal in a future version.
    use content(ContentBlock...)
    static ToolResult
    content(ContentBlock... blocks)
    Creates a successful result containing the given content blocks.
    static ToolResult
    empty()
    Creates a successful result with no structured value and no content.
    static ToolResult
    error(String message)
    Creates a failed result with the given error message.
    static ToolResult
    inputRequired(Map<String,? extends InputRequest> reqs, @Nullable String state)
    Creates a result that requests additional input from the caller before the tool call can complete.
    static ToolResult
    of(Object payload)
    Creates a success result carrying payload as structured content with no text block.
    static ToolResult
    of(Object payload, String text)
    Creates a success result carrying payload as structured content plus an explicit human-readable text block.
    static ToolResult
    raw(String json, String text)
    Creates a success result with a pre-serialized JSON payload.
    static ToolResult
    structured(Object payload)
    Alias for of(Object) with a name that states what the payload becomes (structured content) rather than how it's constructed.
    static ToolResult
    structured(Object payload, String text)
    Alias for of(Object, String) with a name that states what the payload becomes (structured content) rather than how it's constructed.
    static ToolResult
    text(String t)
    Creates a successful result containing a single text content block.
    default ToolResult
    withMeta(String key, Object value)
    Returns a copy of this result with a single _meta entry set.
    default ToolResult
    withMeta(Map<String,Object> m)
    Returns a copy of this result with m merged into its _meta entries; returns this unchanged when m is empty.

  • Method Details

    • withMeta

      default ToolResult withMeta(Map<String,Object> m)
      Returns a copy of this result with m merged into its _meta entries; returns this unchanged when m is empty.
      Parameters:
      m - the _meta entries to merge in
      Returns:
      a result carrying the merged metadata

    • withMeta

      default ToolResult withMeta(String key, Object value)
      Returns a copy of this result with a single _meta entry set.
      Parameters:
      key - the _meta key
      value - the _meta value
      Returns:
      a result carrying the added metadata entry

    • text

      static ToolResult text(String t)
      Creates a successful result containing a single text content block.
      Parameters:
      t - the text
      Returns:
      a successful tool result

    • content

      static ToolResult content(ContentBlock... blocks)
      Creates a successful result containing the given content blocks.
      Parameters:
      blocks - the content blocks
      Returns:
      a successful tool result

    • blocks

      @Deprecated(since="1.0.0-beta.15", forRemoval=true) static ToolResult blocks(ContentBlock... blocks)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use content(ContentBlock...)
      Creates a successful result containing the given content blocks.
      Parameters:
      blocks - the content blocks
      Returns:
      a successful tool result

    • of

      static ToolResult of(Object payload, String text)
      Creates a success result carrying payload as structured content plus an explicit human-readable text block.
      Parameters:
      payload - the structured payload
      text - the text content for the content block
      Returns:
      a successful tool result

    • structured

      @ExperimentalApi static ToolResult structured(Object payload, String text)
      Alias for of(Object, String) with a name that states what the payload becomes (structured content) rather than how it's constructed.
      Parameters:
      payload - the structured payload
      text - the text content for the content block
      Returns:
      a successful tool result

    • of

      static ToolResult of(Object payload)
      Creates a success result carrying payload as structured content with no text block.

      The server emits the serialized JSON of payload as the text content at encode time (MCP backwards-compat for structured results). Use of(Object, String) to supply an explicit human-readable text block instead.

    • structured

      @ExperimentalApi static ToolResult structured(Object payload)
      Alias for of(Object) with a name that states what the payload becomes (structured content) rather than how it's constructed.
      Parameters:
      payload - the structured payload
      Returns:
      a successful tool result

    • error

      static ToolResult error(String message)
      Creates a failed result with the given error message.
      Parameters:
      message - the error message
      Returns:
      a failed tool result

    • empty

      static ToolResult empty()
      Creates a successful result with no structured value and no content.

    • raw

      static ToolResult raw(String json, String text)
      Creates a success result with a pre-serialized JSON payload. The bytes skip the Jackson value-to-tree conversion of ordinary structured values and are parsed once at envelope encoding (plus once more when output schema validation is active).
      Parameters:
      json - a pre-serialized JSON object string
      text - the text content for the content block

    • inputRequired

      static ToolResult inputRequired(Map<String,? extends InputRequest> reqs, @Nullable String state)
      Creates a result that requests additional input from the caller before the tool call can complete.
      Parameters:
      reqs - the requested inputs, keyed by request id
      state - an opaque state token to echo back with the caller's response, or null
      Returns:
      a result signaling that input is required