AI Tools Reference

When a user runs a prompt, the AI model can do more than answer in text.

It can call tools: small functions that ReviewStudio provides. A tool call is how the model puts a highlight on the page, reads the review notes, or looks something up. This page lists the tools, when they are available, and what the model is told about each of them.

You do not have to tell the model how to format tool calls. The tool descriptions already do that. Your prompt only has to say what you want and when a tool should be used. If your prompt and a tool description disagree, the model gets confused, so describe the goal and leave the format to the tool.

How to Read This Page

Tool name: the exact name the model uses. You can mention it in a prompt ("call get_notes with which set to other"). Spell it exactly as shown.

Description: the text the model reads.

Parameters: the fields the model fills in for a call. Required fields must always be there, optional fields can be left out.

Page numbers always start at 0, so the first page is page 0.

Coordinates are always on a scale from 0 to 1000 across the whole page or image: [ymin, xmin, ymax, xmax] for a box and [y, x] for a point. The top left corner is [0, 0] and the bottom right corner is [1000, 1000]. Note that y (up and down) comes first.

Tools at a Glance

Tool

What it does

record_text_annotation

Marks a piece of text in a document, for example a spelling mistake, with an explanation and an optional correction.

record_visual_annotation

Marks a region of a page or image with a box and a label, for example a logo, a person or a QR code.

get_text_style_info

Looks up the font, size, style and color of a piece of text in a document.

get_notes

Reads the review notes (comments), replies and tasks, with their position on the page. Only in compare mode.

load_document_version

Attaches another version of the same document so the model can compare. Only when the document has more than one version.

Which Tools Are Available

ReviewStudio decides per request which tools the model gets. The columns are the file types a prompt can be made for (applicableTypes of a prompt).

Tool

document

image

video

Extra condition

record_text_annotation

yes

no

no

None.

record_visual_annotation

yes

yes

yes

None.

get_text_style_info

yes

no

no

Only for documents that ReviewStudio shows as vector pages (PDF).

get_notes

yes

yes

yes

Only in compare mode.

load_document_version

yes

yes

yes

Only when the item has two or more versions.

imported tools

yes

yes

yes

Only for prompts that have an OpenAPI description.

Things to know:

Selecting a region (focus) turns the request into an image request. The model then sees one or more cropped images and the text tools are not offered. Prompts for regions should use record_visual_annotation.

Video and audio are sent as media. The model can mark a region with record_visual_annotation, but the page number is then the time in the media, not a page.


Tool Details

record_text_annotation

Description. Records one matched, extracted, highlighted or corrected text segment. The model is told to call it once for every segment it finds, all calls in the same answer, and not to call it at all when nothing is found.

Parameters

Parameter

Type

Required

Meaning

matched_text

text

yes

The exact word, phrase or sentence that matches.

explanation

text

yes

Why this text was picked, for example "Spelling error".

page

whole number

yes

The page where the text was found, starting at 0.

context_snippet

text

yes

A unique string of 5 to 7 words around the match, so ReviewStudio can find the exact spot.

suggested_replacement

text

no

The correction. Leave out when no correction is needed.

Good for: spelling and grammar checks, finding phrases, legal wording, terminology checks.

Tip for prompts: say what kind of explanation you want (one short sentence, or the rule that was broken), the model otherwise picks its own.

record_visual_annotation

Description. Records one located visual element, object, image or person. The model is told to call it once per element, and not to use it for text segments or spelling errors.

Parameters

Parameter

Type

Required

Meaning

page

whole number

yes

The page where the element is, starting at 0. For selected regions it is the region number, for media it is the time.

image_description

text

yes

A short description of the element. This is the label the user sees.

box_2d

list of 4 whole numbers

yes

[ymin, xmin, ymax, xmax] on the 0 to 1000 scale.

Good for: finding logos, QR codes, faces, products, layout problems, and reporting a verdict on a region.

Tip for prompts: there is no separate field for a verdict or a note id. If you want one, tell the model to put it at the start of image_description, for example "not addressed, note 12: logo is still left aligned".

get_text_style_info

Description. Looks up the font (family, size, style, weight) and color of one piece of text. It moves the viewer to the requested page to inspect it.

Parameters

Parameter

Type

Required

Meaning

page

whole number

yes

The page to search, starting at 0.

context_snippet

text

yes

A unique string of 5 to 7 words from the document to find the spot.

matched_text

text

no

The exact word or phrase inside the snippet whose style is wanted. Without it the start of the snippet is used.

Result. found (true or false), the page, and the font information. This tool gives information back to the model, it does not draw anything.

Good for: checking that headings use the same font, finding where a specific font is used, checking brand colors.

get_notes

Description. Returns the review notes (comments) with their replies and tasks. A note without text is private. A users list in the result turns a user id into a name.

Parameters

Parameter

Type

Required

Meaning

which

current or other

yes

current for the document the user is looking at. other for the other version in compare mode.

Result. For each note:

Field

Meaning

noteid, id, text, userid, modified

Who wrote what and when. No text means the note is private.

frame, frameStr

The page (or time) the note belongs to, and its label.

replies

The replies, in order.

task

The current task of the note, if there is one.

location

global (no position), pin (a point) or shape (drawn shapes).

pin.point_2d

[y, x] of the point the note is attached to. Present for pin and shape notes.

shapes

For each drawn shape: its kind (for example square, circle, arrow, brush, textsel) and its box_2d.

box_2d

One box around all shapes of the note.

All coordinates use the same 0 to 1000 scale as record_visual_annotation, so a box from a note can be used directly to look at the same place on the current version. For a shape note, the pin is where the note is attached to the shape (for example the root of an arrow), not the center of the box.

Good for: summarizing feedback, counting open tasks, checking whether notes were addressed in a new version.

Only in compare mode. Outside compare mode the tool does not exist. Asking for other when there is no other version returns an error.

load_document_version

Description. Fetches another version of the current document and attaches it to the conversation, so the model can look at it like the open document. The description lists all versions from newest to oldest, marks the one the user is looking at as (current), and in compare mode marks the version on the other side as (shown on the other side in compare mode).

Parameters

Parameter

Type

Required

Meaning

version

text, one of the listed version names

yes

The version to load. The next (newer) version is the one before the current version in the list, the previous (older) version is the one after it. The current version is not offered, it is already attached.

Result. status: ok and the name of the version, or an error when the file is not available.

Good for: "what changed since the previous version", "check that the requested changes are in the next version".

Tip for prompts: version names are different for every document. Refer to them by role ("the previous version", "the version marked as shown on the other side") and not by name.