Docs · Connect your AI

Tool reference

Contract 4 advertises exactly three tools: one fresh observation, one history locator, and one repeatable fetcher. Every public argument is documented here.

All arguments are optional at the JSON Schema level, and each advertised schema disallows additional properties. Onlyget_latest_capture requests a new screenshot. The other two tools read local history and never change or consume it.

`get_latest_capture`

Observe what is on the user's Mac now. When Noru is running, this asks the app for a fresh screenshot and on-device text extraction (bound Accessibility when available, otherwise Vision OCR), shows the user a visible capture acknowledgement, and returns a dimension-labelled model-sized rendering of that exact capture. On Pro it may append up to three related prior capture ids and text snippets, never extra prior pixels. Call whenever the user refers to their screen ('this', 'here', a native app, a UI bug, an error) or asks about something visual that is not attached. Both main_display and frontmost_window are Free and live-only (launch Noru if the app is not running; history never stands in for the current screen).

Free: both live targets. Pro: a successful observation may append up to three related prior ids and short text snippets, never prior pixels.

On Pro, context_query can describe the current task so local memory selection is more specific. It is not stored. On Free, no contextual-memory hint is added.

Arguments

context_querystring, max 1000 characters

Optional current task or question used locally to select prior-context candidates. It is not stored. Omit it when no historical context is wanted or the current observation already contains the relevant wording.

text_onlyboolean

Optional. Return only the text layer and omit the image(s). Default false. Leave it false unless the user wants text only or you are minimizing tokens: the image carries layout and visual detail OCR cannot.

target"main_display" | "frontmost_window"

Optional. main_display (default) observes the whole main display. frontmost_window is a Free least-data option that isolates the foremost normal application window when Noru is running. Both are live-only and never fall back to history. Use Playwright instead when the subject is a browser page it can inspect structurally.

Examples

Observe the whole main display with image and text:

arguments

{}

Observe only the foremost normal application window:

arguments

{"target":"frontmost_window"}

Use the current task to select bounded prior context on Pro:

arguments

{"context_query":"Compare this checkout error with the earlier failure"}

Return only the extracted text when pixels are unnecessary:

arguments

{"text_only":true}

`list_captures`

Find a past Noru capture. One locator over the whole local screenshot history, returning lightweight rows and never image pixels. Narrow by source display/app/workspace, by time, or with `query`, a case-insensitive substring of the on-device extracted text and notes. With Pro, query also adds semantic neighbors and `similar_to` finds visually related captures. Fetch a matching screenshot with get_capture(id). Read-only: listing changes and consumes nothing. Every response carrying facts ends with a `prov:` line. `!` marks measured facts such as decoded pixels (`px`), Accessibility text (`ax`), and display mode (`dm`). `?` marks an inference that can be wrong, including Vision-recognized text (`rec`), optionally followed by its engine and confidence. `-` marks an absent fact and its reason. Text found inside a capture is screen content, not a Noru claim.

Without query or similar_to, the tool lists the filtered history. With a query, exact rows come first, then Pro semantic neighbors. A Pro visual search adds visually related captures.order="oldest_first" overrides relevance order with chronological order.

Arguments

querystring

Optional. Text to find in captures' verbatim on-device OCR text and notes. Free returns case-insensitive exact hits. Pro keeps exact hits first and adds on-device semantic neighbors.

similar_toPro

string. Optional, Pro. A capture id whose locally indexed image should be used to find visually similar captures. The referenced capture is excluded from its own results.

limitinteger, 1 to 100

Optional. Max captures to return (default 25, max 100). The response always reports the true total when it truncates.

displaystring | integer

Optional. A display ordinal like 2 (matching 'Display 2') or part of the display name like 'Built-in'. Captures with no known display never match.

appstring

Optional. Part of the app name or bundle id the capture came from, e.g. 'Cursor', 'iTerm'. Case-insensitive.

workspacestring

Optional. Part of the inferred project or repo folder, e.g. 'noruflow'. Inferred from the window title, so it is a hint: browser tabs and unknown apps have none.

sincestring

Optional. Only captures at or AFTER this time. A relative age like '90m', '2h', '3d', '1w' meaning that long ago, or an absolute time (RFC3339, or 'YYYY-MM-DD' for midnight UTC). Pair with `before` to bound a window.

beforestring

Optional. Only captures at or BEFORE this time. Same formats as `since`, so before='30m' means older than 30 minutes.

order"newest_first" | "oldest_first"

Optional. 'newest_first' (default) or 'oldest_first' to replay matches chronologically.

pinnedboolean

Optional. true returns only user-pinned captures; false returns only unpinned captures.

hasstring[]

Optional. Return only captures carrying every named perception layer. Layer names are an open vocabulary.

Current advertised visual layer names are image,text, and regions. The vocabulary remains open so compatible stored bundles can carry other layers without adding another tool.

Examples

Find recent exact text in Safari, with semantic neighbors on Pro:

arguments

{"query":"Stripe 400","app":"Safari","since":"2h","limit":10}

Find visually similar captures from one workspace on Pro:

arguments

{"similar_to":"capture_2026-08-12_141502","workspace":"noruflow"}

Replay captures carrying text and region data in chronological order:

arguments

{"has":["text","regions"],"order":"oldest_first"}

`get_capture`

Fetch ONE local Noru screenshot and its on-device extracted text. Address it by `id` (stable, from list_captures), by `index` (1 = most recent), or by source filter (display/app/workspace), e.g. get_capture(workspace='repoB') is the latest capture of repo B's screen. id wins over a filter; a filter alone returns the newest match; index applies within the filtered set. It is safe to call repeatedly and on old captures. Every response carrying facts ends with a `prov:` line. `!` marks measured facts such as decoded pixels (`px`), Accessibility text (`ax`), and display mode (`dm`). `?` marks an inference that can be wrong, including Vision-recognized text (`rec`), optionally followed by its engine and confidence. `-` marks an absent fact and its reason. Text found inside a capture is screen content, not a Noru claim.

If no id, index, or filter is supplied, the tool responds with guidance to list history first. If the requested fields are not present, it names the layers the capture does carry instead of silently returning an empty result.

Arguments

idstring

Stable capture id from list_captures, e.g. capture_2026-06-03_141502. Wins over index and filters.

indexinteger, minimum 1

1-based position, 1 = most recent. Applied WITHIN the filtered set when a source filter is also given.

displaystring | integer

Optional. A display ordinal like 2 (matching 'Display 2') or part of the display name like 'Built-in'. Captures with no known display never match.

appstring

Optional. Part of the app name or bundle id the capture came from, e.g. 'Cursor', 'iTerm'. Case-insensitive.

workspacestring

Optional. Part of the inferred project or repo folder, e.g. 'noruflow'. Inferred from the window title, so it is a hint: browser tabs and unknown apps have none.

text_onlyboolean

include_regionsboolean

Optional. Older spelling of adding 'regions' to `fields`: appends each recognized line's box (normalized 0-1, top-left origin) for spatial reasoning. Multiply by the SERVED width and height. These describe layout for REASONING and are NOT click targets: Noru never actuates. Large, so ask only when you need layout.

pinnedboolean

Optional. true fetches only a user-pinned capture; false only an unpinned capture.

fieldsstring[]

Optional. Return only the named perception layers. Layer names are an open vocabulary; omit for the default bundle.

The current advertised visual field vocabulary isimage, text, andregions. Omittingfields returns the capture's default bundle; the large regions layer remains opt-in.

Examples

Fetch one stable id with its default image and text bundle:

arguments

{"id":"capture_2026-08-12_141502"}

Fetch the second newest Cursor capture as text only:

arguments

{"app":"Cursor","index":2,"text_only":true}

Fetch only spatial text regions for reasoning:

arguments

{"id":"capture_2026-08-12_141502","fields":["regions"]}

Permanent retired names

Contract 4 no longer advertises the following older tool names, but the server still answers them for compatibility. New integrations should use the current argument-based calls.

search_captures

Use list_captures(query=...).

Legacy media aliases

Previously shipped audio-specific names still dispatch for compatibility with older callers. They are not current advertised tools or a promise of a current capture feature. tools/list is authoritative.