directive @tool

Descriptions may be set for the tool and its parameters, if a description is not provided a default is generated.

Descriptions may be templates that include {variable} where variable is one of:

• endpoint_folder - the folder of the endpoint, set at deploy time.

• endpoint_name - the name of the endpoint, set at deploy time.

• graphql_tool - A generic description of a GraphQL tool.

• schema_description - the GraphQL schema description (from schema definition).

• schema_sdl - the GraphQL schema's SDL as defined by the visibility patterns in @tool(graphql:).

The description argument specifies the tool description. If not provided:

• For a prescribed tool, the description is taken from the GraphQL operation definition in the persisted document.

• Otherwise, a default description is used.

The descriptions argument overrides default descriptions for the tool's parameters.

For a GraphQL tool the name of the tool's parameters are query, operationName and variables corresponding to standard parameters for a GraphQL HTTP request.

For a prescribed tool descriptions can be set for variables and the names of variables defined by the tool's GraphQL operation. If not provided, variable descriptions are taken from the operation in the persisted document.

The graphql argument specifies the tool is a GraphQL tool and sets the visibility of fields that will be exposed for the tool and available for templating as {schema_sdl}.

The name argument specifies the tool name, which must be unique within the schema.

The name is a template that can include variables for the endpoint folder and name, for example: {endpoint_folder}-{endpoint_name}, but no other template variables are supported.

The prescribed argument specifies a predefined GraphQL operation for this tool. prescribed is the operation name from a persisted document supplied through @sdl(executables:) with persist: true.

This defines a GraphQL tool that is the subset of the schema rooted at the single field Query.customer.

extend schema
  @tool(
    name: "customer-lookup"
    description: "Customer lookup tool. {graphql_tool}"
    graphql: {expose: true, types: "Query", fields: "customer"}
  )

The schema will include any schema elements that are reachable from Query.customer.

The tool has three parameters query (required), operationName and variables and can be executed through the MCP method tools/call by passing arguments that make up a valid GraphQL request for the tool's schema.

This defines a GraphQL tool that is the subset of the schema rooted at the fields Query.employee and Query.employees.

In addition the schema is pruned at the fields ssn, address and salary in the type Employee so that the tool cannot access sensitive information.

extend schema
  @tool(
    name: "employee-lookup"
    description: "Employee lookup tool. {graphql_tool}"
    graphql: [
      {expose: true, types: "Query", fields: "employee|employees"}
      {expose: false, types: "Employee", fields: "ssn|salary|address"}
    ]
  )

This defines a prescribed tool that maps to the persisted GraphQL operation CustomerLookup. The tool description will have a single required object parameter variables with properties corresponding to the variable definitions of the operation.

extend schema
  @sdl(executables: [{document: "ops.graphql", persist: true}])
  @tool(
    name: "customer-lookup"
    description: "Lookup customer information"
    prescribed: "CustomerLookup"
    descriptions: [{name: "email", value: "Email of the customer"}]
  )

The persisted document ops.graphql contains a GraphQL operation such as:

query CustomerLookup($email: String!) {
  customer(email: $email) {
    id
    name
    email
    address {
      street
      city
      state
    }
  }
}

This will result in an MCP tool description of:

{
  "name": "customer-lookup",
  "description": "Lookup customer information",
  "inputSchema": {
    "type": "object",
    "properties": {
      "variables": {
        "properties": {
          "email": {
            "description": "Email of the customer",
            "type": "string"
          }
        },
        "required": ["email"],
        "type": "object"
      }
    },
    "required": ["variables"]
  }
}

Prescribed tools support operation descriptions in the persisted GraphQL document. When provided, these descriptions are automatically used by MCP tools instead of requiring explicit descriptions in the @tool directive.

extend schema
  @sdl(executables: [{document: "ops.graphql", persist: true}])
  @tool(
    name: "customer-lookup"
    prescribed: "CustomerLookup"
  )

The persisted document ops.graphql contains a GraphQL operation with operation and variable descriptions such as:

"""
Lookup customer information by email
"""
query CustomerLookup("""email of the customer""" $email: String!) {
  customer(email: $email) {
    id
    name
    email
    address {
      street
      city
      state
    }
  }
}

This will result in the same MCP tool description as the previous example:

{
  "name": "customer-lookup",
  "description": "Lookup customer information by email",
  "inputSchema": {
    "type": "object",
    "properties": {
      "variables": {
        "properties": {
          "email": {
            "description": "email of the customer",
            "type": "string"
          }
        },
        "required": ["email"],
        "type": "object"
      }
    },
    "required": ["variables"]
  }
}