chore: add snippet for prescribed tool with descriptions #79
Conversation
Signed-off-by: Ratnakar Asara <rasara@us.ibm.com>
Signed-off-by: Ratnakar Asara <rasara@us.ibm.com>
ddebrunner
left a comment
ddebrunner
left a comment
There was a problem hiding this comment.
Nice snippet, I think some minor cleanup to better introduce the concept, as it's totally new.
| @@ -0,0 +1,110 @@ | |||
| # Prescribed Tools with Descriptions | |||
|
|
|||
| This sample demonstrates how to use the `@tool` directive with prescribed operations that contains descriptions that can be used through to create MCP (Model Context Protocol) tools. | |||
There was a problem hiding this comment.
"prescribed tools"
"persisted operations"
are the terms
Not "prescribed operations"
There was a problem hiding this comment.
Might be good to qualify "operation" as "GraphQL operation" (with a link to the spec) as the first mention.
|
|
||
| ## Overview | ||
|
|
||
| The sample implements a mock weather service API with a simple operations, Weather forecast for a city |
There was a problem hiding this comment.
"simple operations"
Remove "simple", and there's only a single operation right?
| - The `@sdl` directive that includes persisted operations | ||
|
|
||
| 2. An operations file (`operations.graphql`) that contains: | ||
| - Documented GraphQL operations with descriptions |
There was a problem hiding this comment.
"Documented ... with descriptions" is redundant?
There was a problem hiding this comment.
Only a single operation though?
| # Prescribed Tools with Descriptions | ||
|
|
||
| This sample demonstrates how to use the `@tool` directive with prescribed operations that contains descriptions that can be used through to create MCP (Model Context Protocol) tools. | ||
|
|
There was a problem hiding this comment.
I think an overview of what a "prescribed tool" is would be essential at this point.
| ) | ||
| ``` | ||
|
|
||
| The operation itself can include descriptions: |
There was a problem hiding this comment.
add "(new to GraphQL September 2025)"
| @@ -0,0 +1,183 @@ | |||
| schema | |||
| @sdl( | |||
| files: [] | ||
| executables: [{ document: "operations.graphql", persist: true }] | ||
| ) | ||
| @tool(name: "weather-lookup", prescribed: "WeatherForecast") { |
| }, | ||
| forecast: [ | ||
| { | ||
| date: forecastDates[0], |
There was a problem hiding this comment.
test is subject to failure if it's run around midnight
|
@asararatnakar Can you "refactor" this a little to just be how to define a prescribed tool, and drop the mentions of "with descriptions (i.e. put it in I think this is the way we want to encourage prescribed tool definitions, thus the "with descriptions" is not really important, though it is important that we show operations having descriptions. Then in the future I could see a "with descriptions" variant, that shows how descriptions in |
Signed-off-by: Ratnakar Asara <rasara@us.ibm.com>
ddebrunner
left a comment
ddebrunner
left a comment
There was a problem hiding this comment.
GTG - the link to persisted docs in the spec is wrong though
| @@ -0,0 +1,141 @@ | |||
| # Prescribed Tools | |||
|
|
|||
| A **prescribed tool** is a tool that maps to a specific [GraphQL operation](https://spec.graphql.org/September2025/#sec-Language.Operations) in a [persisted document](https://spec.graphql.org/September2025/#sec-Persisted-Documents). The `@tool(prescribed:)` argument links the tool definition to an operation name in a persisted document. This approach provides a structured way to expose specific GraphQL operations as tools that can be called by AI models. | |||
There was a problem hiding this comment.
persisted document is not a GraphQL spec concept, at least not that spec, maybe a reference to the persisted snippet.
2 participants
Description
This snippet shows how to use prescribed tool using
@tooldirective to define operations with descriptions.also demonstrates how these descriptions help create MCP tools that AI models can understand and use.