Skip to contents

Type Specifications for MCP Protocol

Source: R/type-conversion-utilities.R
type_boolean.Rd

Specifies object types for MCP tool calling and structured data extraction. Based on JSON Schema standards for API compatibility with comprehensive R type mapping. Enables precise type definitions for tool parameters and return values through standardized type specification system.

  • type_boolean(), type_integer(), type_number(), and type_string() each represent scalars. These are equivalent to length-1 logical, integer, double, and character vectors (respectively).

  • type_enum() is equivalent to a length-1 factor; it is a string that can only take the specified values.

  • type_array() is equivalent to a vector in R. You can use it to represent an atomic vector: e.g. type_array(type_boolean()) is equivalent to a logical vector and type_array(type_string()) is equivalent to a character vector). You can also use it to represent a list of more complicated types where every element is the same type (R has no base equivalent to this), e.g. type_array(type_array(type_string())) represents a list of character vectors.

  • type_object() is equivalent to a named list in R, but where every element must have the specified type. For example, type_object(a = type_string(), b = type_array(type_integer())) is equivalent to a list with an element called a that is a string and an element called b that is an integer vector.

  • type_json_object() is equivalent to an arbitrary JSON object / named list. Use it when the tool should receive flexible key-value data as a named list instead of a fixed schema declared with type_object().

  • type_json_array() is equivalent to an arbitrary JSON array / list. Use it when the tool should receive flexible list payloads instead of a homogenous typed vector declared with type_array().

Usage

type_boolean(description = NULL, required = TRUE, error = NULL)

type_integer(description = NULL, required = TRUE, error = NULL)

type_number(description = NULL, required = TRUE, error = NULL)

type_string(description = NULL, required = TRUE, error = NULL)

type_enum(values, description = NULL, required = TRUE, error = NULL)

type_array(items, description = NULL, required = TRUE, error = NULL)

type_object(
  .description = NULL,
  ...,
  .required = TRUE,
  .additional_properties = FALSE,
  .error = NULL
)

type_json_object(description = NULL, required = TRUE, error = NULL)

type_json_array(description = NULL, required = TRUE, error = NULL)

Arguments

description, .description

The purpose of the component. This is used by the LLM to determine what values to pass to the tool or what values to extract in the structured data, so the more detail that you can provide here, the better.

required, .required

Is the component or argument required?

In type descriptions for structured data, if required = FALSE and the component does not exist in the data, the LLM may hallucinate a value. Only applies when the element is nested inside of a type_object().

In tool definitions, required = TRUE signals that the LLM should always provide a value. Arguments with required = FALSE should have a default value in the tool function's definition. If the LLM does not provide a value, the default value will be used.

values

Character vector of permitted values.

items

The type of the array items. Can be created by any of the type_ function.

...

Name-type pairs defineing the components that the object must possess.

.additional_properties

Can the object have arbitrary additional properties that are not explicitly listed? Only supported by Claude.

Details

Type Specifications for MCP Protocol

Examples

# An integer vector
type_array(type_integer())
#> $type
#> [1] "array"
#> 
#> $items
#> $type
#> [1] "integer"
#> 
#> $description
#> NULL
#> 
#> $required
#> [1] TRUE
#> 
#> $error
#> NULL
#> 
#> attr(,"class")
#> [1] "mcpr_type"
#> 
#> $description
#> NULL
#> 
#> $required
#> [1] TRUE
#> 
#> $error
#> NULL
#> 
#> attr(,"class")
#> [1] "mcpr_type"

# The closest equivalent to a data frame is an array of objects
type_array(type_object(
  x = type_boolean(),
  y = type_string(),
  z = type_number()
))
#> $type
#> [1] "array"
#> 
#> $items
#> $type
#> [1] "object"
#> 
#> $properties
#> $properties$x
#> $type
#> [1] "boolean"
#> 
#> $description
#> NULL
#> 
#> $required
#> [1] TRUE
#> 
#> $error
#> NULL
#> 
#> attr(,"class")
#> [1] "mcpr_type"
#> 
#> $properties$y
#> $type
#> [1] "string"
#> 
#> $description
#> NULL
#> 
#> $required
#> [1] TRUE
#> 
#> $error
#> NULL
#> 
#> attr(,"class")
#> [1] "mcpr_type"
#> 
#> $properties$z
#> $type
#> [1] "number"
#> 
#> $description
#> NULL
#> 
#> $required
#> [1] TRUE
#> 
#> $error
#> NULL
#> 
#> attr(,"class")
#> [1] "mcpr_type"
#> 
#> 
#> $description
#> NULL
#> 
#> $required
#> [1] TRUE
#> 
#> $additional_properties
#> [1] FALSE
#> 
#> $error
#> NULL
#> 
#> attr(,"class")
#> [1] "mcpr_type"
#> 
#> $description
#> NULL
#> 
#> $required
#> [1] TRUE
#> 
#> $error
#> NULL
#> 
#> attr(,"class")
#> [1] "mcpr_type"

# There's no specific type for dates, but you use a string with the
# requested format in the description (it is not guaranteed that you will
# get this format back, but you should most of the time)
type_string("The creation date, in YYYY-MM-DD format.")
#> $type
#> [1] "string"
#> 
#> $description
#> [1] "The creation date, in YYYY-MM-DD format."
#> 
#> $required
#> [1] TRUE
#> 
#> $error
#> NULL
#> 
#> attr(,"class")
#> [1] "mcpr_type"
type_string("The update date, in dd/mm/yyyy format.")
#> $type
#> [1] "string"
#> 
#> $description
#> [1] "The update date, in dd/mm/yyyy format."
#> 
#> $required
#> [1] TRUE
#> 
#> $error
#> NULL
#> 
#> attr(,"class")
#> [1] "mcpr_type"