directive @tool

Edit online

@tool directive defines a Model Context Protocol (MCP) function tool that can be executed as a GraphQL request against the schema's deployed endpoint.

Overview

Tool calling allows language models (LLMs) to work with external tools by following user-defined instructions. The model figures out the required inputs for a tool, and the tool does the actual work.

@tool defines a tool that makes fields selections against its schema.

A GraphQL tool is specified by a GraphQL schema, an LLM generates a GraphQL request that can be made against that schema. This request may just be the GraphQL query or mutation operation, or the LLM may separate the request into an operation and the variables the operation requires.

A GraphQL tool is specified by the directive argument @tool(graphql:), which specifies the schema, which is either the endpoint's full schema or a more typically a subset. The schema is further subset for any request by the endpoint's field access policies, ensuring that a tool call only has access to the fields that are accessible to the authorization of the request.

A prescribed tool maps to a persisted GraphQL operation of the endpoint's schema, an LLM needs to generate values required for the operation's GraphQL variables.

A prescribed tool is specified by the directive argument @tool(prescribed:), providing the name of a persisted GraphQL operation. With field access policies, a tool call must have authorization to select all fields within the operation.

Accessing Tool Descriptions

A deployed schema has a GraphQL endpoint (folder/name/graphql) and an MCP endpoint (folder/name/mcp).

For example with the GraphQL endpoint:

https://newyork.us-east-a.ibm.stepzen.net/api/customers/graphql

the MCP endpoint is at:

https://newyork.us-east-a.ibm.stepzen.net/api/customers/mcp

The MCP endpoint is a stateless HTTP implementation that supports MCP protocol version 2025-03-26.

Tool descriptions defined by @tool are returned by the MCP endpoint, using the method tools/list.

Making Tool Calls

An LLM response contains a tool name and arguments that must be used to make the call.

Tool calls are made by calling the MCP endpoint using the method tools/call.

Tool Descriptions

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:).

Default Tool

If no tool is specified then a single default tool is created and exposed through the MCP endpoint.

The default tool is equivalent to the following tool:

@tool(
  name: "{endpoint_folder}-{endpoint_name}"
  graphql: {expose: true, types: "Query", fields: ".*"}
)

GraphQL Tool Virtual Endpoint

A GraphQL tool definition exposes a virtual GraphQL endpoint with its schema being the subset defined by the @tool(graphql:) argument. The virtual endpoint is available at folder/name/tools/tool-name/graphql, for example:

https://newyork.us-east-a.ibm.stepzen.net/api/customers/tools/customer-lookup/graphql

The virtual endpoint shares the same field access policies as the main GraphQL endpoint (folder/name/graphql). The virtual endpoint's schema is further subset for any request by field access policies, ensuring that only fields that are accessible to the authorization of the request are exposed.

Arguments

description: String

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.
descriptions: [StepZen_NamedValue!]

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.

graphql: [StepZen_VisibilityPattern!]
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}.
name: String!

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.

prescribed: String
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.

Locations

repeatable

Type System: SCHEMA

Examples

GraphQL tool

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.

GraphQL tool with schema pruning

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"}
    ]
  )
Prescribed tool

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
    }
  }
}
Prescribed tool with operation descriptions

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
    }
  }
}