Tools
Every tool lives in src/Presentation/Tools, one static class per feature. Arguments are JSON, named in camelCase. Every tool returns its result twice: as a text content block holding JSON, for models that read, and as structuredContent, for clients that parse, with an output schema in the tool’s listing. After the text comes a resource_link block for each movie, author or review in the result, pointing at its movies://, authors:// or reviews:// resource, so a client can open it. In a solution created with --include-auth, every tool needs a token.
| Tool | Title | Read-only | Destructive | Idempotent |
|---|---|---|---|---|
movies_search |
Search movies | yes | yes | |
movies_get |
Get movie | yes | yes | |
authors_search |
Search authors | yes | yes | |
reviews_list |
List reviews | yes | yes | |
reviews_write |
Write review | yes | ||
reviews_delete |
Delete review | yes | yes |
Every tool has openWorldHint false: they only ever touch this server’s own database. Every tool also has an icon, a movie, an author or a review, from the brand repository.
movies_search
Section titled “movies_search”Finds movies whose title contains a search term, ignoring case, in title order. Leave the query empty to browse every movie a page at a time.
| Argument | Type | Default | Rules |
|---|---|---|---|
query |
string | none | Up to 100 characters |
offset |
integer | 0 |
0 or more |
limit |
integer | 10 |
1 to 50 |
includeReviews |
boolean | false |
Also return every review of each movie |
{ "items": [ { "id": "cb188ef6-14e7-f85f-2f78-924c2ab26b28", "title": "Deep Space Gardeners", "reviewCount": 5, "averageStars": 3.4, "reviews": null }, { "id": "dfefa450-5454-6a4d-a4aa-95a9b047c17b", "title": "Postcards from Outer Space", "reviewCount": 1, "averageStars": 3, "reviews": null } ], "totalCount": 4, "nextOffset": 2}movies_get
Section titled “movies_get”Gets one movie with its review count, average stars and every review, including each author’s name.
| Argument | Type | Rules |
|---|---|---|
movieId |
guid | An existing movie |
Returns a movie with reviews filled in.
authors_search
Section titled “authors_search”Finds authors by first name, last name or full name, ignoring case, in last-name order. Leave the query empty to browse every author a page at a time.
| Argument | Type | Default | Rules |
|---|---|---|---|
query |
string | none | Up to 100 characters |
offset |
integer | 0 |
0 or more |
limit |
integer | 10 |
1 to 50 |
includeReviews |
boolean | false |
Also return every review each author has written |
reviews_list
Section titled “reviews_list”Lists reviews with their star rating and the title and author of each, in movie-title order. Filter by movie, by author, by words in the review or by a minimum star rating, or pass a reviewId to get one review.
| Argument | Type | Default | Rules |
|---|---|---|---|
movieId |
guid | none | Only reviews of this movie |
authorId |
guid | none | Only reviews by this author |
reviewId |
guid | none | Get this one review instead. The other filters are ignored |
query |
string | none | Only reviews whose text contains it, ignoring case. Up to 100 characters |
minStars |
integer | none | Only reviews with at least this many stars, from 1 to 5 |
offset |
integer | 0 |
0 or more |
limit |
integer | 10 |
1 to 50 |
reviews_write
Section titled “reviews_write”Creates a review of a movie by an author, with optional text, or changes the stars and text of an existing review when reviewId is passed. A review’s movie and author can’t change.
| Argument | Type | Rules |
|---|---|---|
stars |
integer | 1 to 5 |
movieId |
guid | Needed to create a review. An existing movie |
authorId |
guid | Needed to create a review. An existing author |
reviewId |
guid | Leave empty to create. An existing review to change |
text |
string | Optional. Up to 1000 characters. Leave it empty when changing a review to keep its text |
Returns the saved review.
reviews_delete
Section titled “reviews_delete”Permanently deletes a review. The description tells the model to confirm with the user first, and the destructiveHint tells the client the same.
| Argument | Type | Rules |
|---|---|---|
reviewId |
guid | An existing review |
Returns { "reviewId": "...", "deleted": true }.
Results
Section titled “Results”Properties with no value are written as null, not left out, so every result matches its output schema. The schema describes them with anyOf and a null type, which clients that only understand one type per property accept too.
Every search and list tool returns one page.
| Property | Type | Description |
|---|---|---|
items |
array | The results on this page |
totalCount |
integer | The number of results across every page |
nextOffset |
integer | Pass it as offset to get the next page. Null on the last page |
| Property | Type | Description |
|---|---|---|
id |
guid | The movie’s id |
title |
string | The movie’s title |
reviewCount |
integer | How many reviews the movie has |
averageStars |
number | The average rating to one decimal place. Null when there are no reviews |
reviews |
array of review | Every review of the movie. Null unless asked for |
Author
Section titled “Author”| Property | Type | Description |
|---|---|---|
id |
guid | The author’s id |
name |
string | The author’s full name |
reviewCount |
integer | How many reviews the author has written |
averageStars |
number | The average rating they give. Null when there are no reviews |
reviews |
array of review | Every review by the author. Null unless asked for |
Review
Section titled “Review”| Property | Type | Description |
|---|---|---|
id |
guid | The review’s id |
stars |
integer | The rating, from 1 to 5 |
movieId |
guid | The movie’s id |
movieTitle |
string | The movie’s title |
authorId |
guid | The author’s id |
authorName |
string | The author’s full name |
text |
string | What the author said about the movie, or null when there’s no text |
Errors
Section titled “Errors”A failed tool call is a result with isError true and one text block, so the model can read what went wrong and try again. The protocol itself never errors for these.
| Starts with | When |
|---|---|
Validation Failed: |
An argument breaks one of the rules above. Lists every rule it broke, then says to correct the arguments and call again |
Not Found: |
The movie, author or review doesn’t exist. Says which, then which tools return valid ids |
Error: |
Something unexpected happened |
{ "isError": true, "content": [ { "type": "text", "text": "Validation Failed: Stars: A star rating must be between 1 and 5. Correct the arguments and call the tool again." } ]}