# This file is automatically generated by ravepipeline::mcptool_build(). 
# Please never edit this file by hand!
name: ieegio-mcp_tool_volume_info
description: Retrieve detailed header information and metadata for a cached volume
  without loading the full data array. Uses the as_nifti_header function to extract
  NIfTI header fields. This is useful for inspecting volume properties, transformations,
  and file provenance.
parameters:
  type: object
  properties:
    id:
      type: string
      description: 'The digest-based identifier of the cached volume. Example values:
        "a3f5e8d9c1b2", "f7e4b2a1c6d8"'
      examples:
      - a3f5e8d9c1b2
      - f7e4b2a1c6d8
  required:
  - id
category: info
returns:
  type: object
  properties:
    error:
      type: string
      description: Character, error message if success is FALSE
    header:
      type: object
      description: List, NIfTI header information including dimensions, datatypes,
        transformations, and other metadata fields
    format:
      type: string
      description: Character, original file format ("nifti" or "mgz")
    paths:
      type: array
      description: Character vector, file paths associated with this volume
      items:
        type: string
    id:
      type: string
      description: Character, the volume identifier
    success:
      type: boolean
      description: Logical, whether the operation completed successfully
implementation_example: |
  # Read a volume and get detailed header info
  # Note: .state_env is automatically provided when called via MCP.
  # AI does not need to specify this argument. The examples only use
  # .state_env to make the code runnable for demonstration purposes.
  sample_file <- ieegio_sample_data("nifti/rnifti_example.nii.gz")
  state_env <- fastmap::fastmap()
  read_result <- ieegio:::mcp_tool_volume_read(sample_file, .state_env = state_env)
  # Get detailed header information
  ieegio:::mcp_tool_volume_info(id = read_result$id, .state_env = state_env)
  #
  #> $success
  #> [1] TRUE
  #> 
  #> $id
  #> [1] "e1ccd803b62bb9390d3debbd05f32042"
  #> 
  #> $paths
  #> [1] "/Users/dipterix/Library/Caches/org.R-project.R/R/ieegio/sample_data/nifti/rnifti_example.nii.gz"
  #> 
  #> $format
  #> [1] "nifti"
  #> 
  #> $header
  #> NIfTI-1 header
  #>     sizeof_hdr: 348
  #>       dim_info: 0
  #>            dim: 3  96  96  60  1  1  1  1
  #>      intent_p1: 0
  #>      intent_p2: 0
  #>      intent_p3: 0
  #>    intent_code: 0 (Unknown)
  #>       datatype: 8 (INT32)
  #>         bitpix: 32
  #>    slice_start: 0
  #>         pixdim: -1.0  2.5  2.5  2.5  0.0  0.0  0.0  0.0
  #>     vox_offset: 352
  #>      scl_slope: 0
  #>      scl_inter: 0
  #>      slice_end: 0
  #>     slice_code: 0 (Unknown)
  #>     xyzt_units: 10
  #>        cal_max: 2503
  #>        cal_min: 0
  #> slice_duration: 0
  #>        toffset: 0
  #>        descrip: TractoR NIfTI writer v3.0.0
  #>       aux_file: 
  #>     qform_code: 2 (Aligned Anat)
  #>     sform_code: 2 (Aligned Anat)
  #>      quatern_b: 0
  #>      quatern_c: 1
  #>      quatern_d: 0
  #>      qoffset_x: 122.0339
  #>      qoffset_y: -95.18523
  #>      qoffset_z: -55.03814
  #>         srow_x: -2.5000  0.0000  0.0000  122.0339
  #>         srow_y: 0.00000  2.50000  0.00000  -95.18523
  #>         srow_z: 0.00000  0.00000  2.50000  -55.03814
  #>    intent_name: 
  #>          magic: n+1
  #>
execution_time: 0.021
