Skip to main content
Glama

Find Text (OCR)

find_text
Read-onlyIdempotent

Perform OCR on screenshots, images, or video frames to locate text, UI labels, or secrets via query or regex and return match boxes for redaction.

Instructions

OCR (built into Windows) on the screen, an image, or video frames, with line and match boxes in image pixels (add origin for desktop coordinates). Locate UI text or secrets (e.g. regex 'sk-|ghp_|api.?key') to redact. Best-effort: review results.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "find_text"
  }
}

Input Schema

NameRequiredDescriptionDefault
keepNoLive target: keep the capture and return its path (default false: deleted after reading).
inputNoImage or video file to read instead of a live target.
queryNoText to find (case-insensitive, tolerates OCR misreads like I/l, O/0, _/-). Omit to return all text.
regexNoTreat query as a regular expression (case-insensitive).
redactNoAlso return padded match rectangles ready for redact_region's regions.
targetNoLive screen target (full | monitor:<i> | window:... | region:...), or pass input.
backendNoLive target: gdigrab (default) = what is visible; wgc (window:, FFmpeg 8+) = the window even if covered.
maxFramesNoscanEverySec frame cap (default 30; ~1 s each).
timestampNoVideo input: second to read (default 0).
exactTitleNowindow: targets match the whole title only (default false).
returnImageNoReturn the image with matches outlined (default: true with a query).
scanEverySecNoVideo input: scan a frame every N s across the clip (e.g. for secrets before sharing); matches and redactRegions get times. Widens to stay within maxFrames.

Output Schema

NameRequiredDescriptionDefault
imageSizeYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changedv0.47.0
    • changedInput schema / properties / backend / description
      Previous value: -"For a live target: gdigrab (default) reads what is visible; 'wgc' (window: targets, FFmpeg 8+) reads the window's own surface even when other windows cover it."New value: +"Live target: gdigrab (default) = what is visible; wgc (window:, FFmpeg 8+) = the window even if covered."
    • changedInput schema / properties / exactTitle / description
      Previous value: -"For window: targets, match the title exactly (default false)."New value: +"window: targets match the whole title only (default false)."
    • changedInput schema / properties / input / description
      Previous value: -"Or read text from an image or video file (one of target / input)."New value: +"Image or video file to read instead of a live target."
    • changedInput schema / properties / keep / description
      Previous value: -"For a live target: keep the captured screenshot and return its path (default false: it is deleted after reading, since it may show the secrets being looked for)."New value: +"Live target: keep the capture and return its path (default false: deleted after reading)."
    • changedInput schema / properties / maxFrames / description
      Previous value: -"With scanEverySec: most frames to read (default 30); each takes about a second."New value: +"scanEverySec frame cap (default 30; ~1 s each)."
    • changedInput schema / properties / query / description
      Previous value: -"Text to look for. Case-insensitive, and tolerant of common OCR misreads (_ vs -, I vs l, O vs 0; regexes get the _ vs - tolerance). Without a query, all recognised text is returned."New value: +"Text to find (case-insensitive, tolerates OCR misreads like I/l, O/0, _/-). Omit to return all text."
    • changedInput schema / properties / redact / description
      Previous value: -"Also return padded rectangles around each match, ready to pass to redact_region (regions) to cover them. Detection is best-effort: review the result."New value: +"Also return padded match rectangles ready for redact_region's regions."
    • changedInput schema / properties / returnImage / description
      Previous value: -"Return the image inline with matches outlined in red (default true when there is a query)."New value: +"Return the image with matches outlined (default: true with a query)."
    • changedInput schema / properties / scanEverySec / description
      Previous value: -"For a video input: read a frame every N seconds across the whole clip instead of one frame, so text shown at any moment is found (use it to check a clip for secrets before sharing). Each match gets its time, and redactRegions get start/end. The interval widens to stay within maxFrames."New value: +"Video input: scan a frame every N s across the clip (e.g. for secrets before sharing); matches and redactRegions get times. Widens to stay within maxFrames."
    • changedInput schema / properties / target / description
      Previous value: -"Read text live from the screen: 'full' | 'monitor:<index>' | 'window:<title>' (or window:exe=<app.exe> / window:hwnd=<handle>) | 'region:...'."New value: +"Live screen target (full | monitor:<i> | window:... | region:...), or pass input."
    • changedInput schema / properties / timestamp / description
      Previous value: -"For a video input: the second to read (default 0). Ignored with scanEverySec."New value: +"Video input: second to read (default 0)."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": {},
      +  "properties": {
      +    "imageSize": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "height": {
      +          "type": "number"
      +        },
      +        "width": {
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "width",
      +        "height"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "required": [
      +    "imageSize"
      +  ],
      +  "type": "object"
      +}
  2. Changed5 schema fields changedv0.39.0
    • addedInput schema / properties / keep
      Added value: +{
      +  "description": "For a live target: keep the captured screenshot and return its path (default false: it is deleted after reading, since it may show the secrets being looked for).",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / maxFrames
      Added value: +{
      +  "description": "With scanEverySec: most frames to read (default 30); each takes about a second.",
      +  "maximum": 120,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • changedInput schema / properties / query / description
      Previous value: -"Text to look for. Case-insensitive, and tolerant of common OCR misreads (_ vs -, I vs l, O vs 0). Without a query, all recognised text is returned."New value: +"Text to look for. Case-insensitive, and tolerant of common OCR misreads (_ vs -, I vs l, O vs 0; regexes get the _ vs - tolerance). Without a query, all recognised text is returned."
    • addedInput schema / properties / scanEverySec
      Added value: +{
      +  "description": "For a video input: read a frame every N seconds across the whole clip instead of one frame, so text shown at any moment is found (use it to check a clip for secrets before sharing). Each match gets its time, and redactRegions get start/end. The interval widens to stay within maxFrames.",
      +  "exclusiveMinimum": 0,
      +  "type": "number"
      +}
    • changedInput schema / properties / timestamp / description
      Previous value: -"For a video input: the second to read (default 0)."New value: +"For a video input: the second to read (default 0). Ignored with scanEverySec."
  3. First observedv0.32.0

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive, closed-world, so safety is covered; the description adds the genuinely useful trait that OCR is best-effort and results should be reviewed. It also discloses the coordinate frame (image pixels vs. desktop coordinates) and the keep/delete capture behavior. It doesn't mention performance cost beyond the ~1 s/frame note carried in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with what it does and what it returns before the use cases and the best-effort caveat. No filler and no repetition of schema fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 12 optional parameters, an output schema, and full annotation coverage, the description supplies exactly the missing layer: the three input modes (live target, file, video frames), the coordinate semantics of returned boxes, and the accuracy caveat. An agent can pick a mode and interpret results without further reading.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so per-parameter meaning is largely already documented (query fuzziness, regex, redact, backend, scanEverySec, maxFrames). The description's added value is the coordinate-frame distinction, but it references an `origin` option that does not exist anywhere in the input schema, which risks sending the agent after a nonexistent parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (OCR over screen, image, or video frames) and specifies the return artifacts: line and match boxes in image pixels. It also distinguishes itself from capture siblings (screenshot, sample_frames) and from redact_region by positioning its output as input to redaction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete use contexts (locate UI text, hunt secrets via regex like 'sk-|ghp_|api.?key' for redaction) and points at the downstream redact_region tool. It lacks explicit when-not guidance, e.g. when to use transcribe or review_recording instead, or that video scanning should prefer sample_frames if full-clip OCR isn't needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.