Skip to main content
Glama

obsbot_zoom_to_fit

Centers the gimbal on a region from a captured snapshot and zooms so that region fills the frame, using the same snapshot's width and height to avoid framing the wrong area.

Instructions

Frame a region of a frame you just captured: centre the gimbal on it and zoom so the region fills the frame. Give x/y/width/height of the region plus the frameWidth/frameHeight from THE SAME obsbot_capture_snapshot result — mixing a region from one frame with dimensions from another frames the wrong place and cannot be detected. Must come from a snapshot, and takes the same source declaration as obsbot_aim_at_pixel. margin (default 0.1) backs the zoom off by that fraction so the region isn't framed edge-to-edge; the tighter of the region's two axes decides the zoom, so the WHOLE region stays visible rather than being cropped on one side. Moves the gimbal BEFORE zooming, since zooming first can push the region's centre out of frame. Refuses on the same conditions as obsbot_aim_at_pixel: AI tracking active, the camera was asleep (waking it moves the gimbal and invalidates the frame), the FOV mode can't be decoded, a corrupt zoom reading, or the region's centre lying past vertical from the current pose, or a frame that isn't 16:9 (obsbot_capture_snapshot always returns 16:9; a non-16:9 pair looks transposed). Also refuses a region that isn't within the frame (edges included), or has non-positive width/height. The requested zoom is clamped to the camera's [1x, 4x] magnification range and reported via clamped; a partial fit still moves and zooms to the limit. Zoom ramps rather than jumping, so the tool polls the status block for up to 3s waiting for it to arrive and returns settled:false (not an error) if it didn't — a frame captured mid-ramp is at an unknown magnification, so check settled before trusting a follow-up snapshot.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "x": "<x>",
      "y": "<y>",
      "width": "<width>",
      "height": "<height>",
      "frameWidth": "<frameWidth>",
      "frameHeight": "<frameHeight>"
    },
    "name": "obsbot_zoom_to_fit"
  }
}

Input Schema

NameRequiredDescriptionDefault
xYes
yYes
widthYes
cameraNo
heightYes
marginNo
sourceNodevice
frameWidthYes
frameHeightYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed17 schema fields changedv0.9.6
    • removedInput schema / properties / frameHeight / allOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "minimum": 1,
      -    "type": "number"
      -  }
      -]
    • addedInput schema / properties / frameHeight / minimum
      Added value: +1
    • addedInput schema / properties / frameHeight / type
      Added value: +"number"
    • removedInput schema / properties / frameWidth / allOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "minimum": 1,
      -    "type": "number"
      -  }
      -]
    • addedInput schema / properties / frameWidth / minimum
      Added value: +1
    • addedInput schema / properties / frameWidth / type
      Added value: +"number"
    • removedInput schema / properties / height / allOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]
    • addedInput schema / properties / height / type
      Added value: +"number"
    • removedInput schema / properties / margin / allOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "minimum": 0,
      -    "type": "number"
      -  }
      -]
    • addedInput schema / properties / margin / minimum
      Added value: +0
    • addedInput schema / properties / margin / type
      Added value: +"number"
    • removedInput schema / properties / width / allOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]
    • addedInput schema / properties / width / type
      Added value: +"number"
    • removedInput schema / properties / x / allOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]
    • addedInput schema / properties / x / type
      Added value: +"number"
    • removedInput schema / properties / y / allOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]
    • addedInput schema / properties / y / type
      Added value: +"number"
  2. Addedv0.7.0
  3. Removedv0.6.2
  4. First observedv0.6.2

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: mutation ordering (gimbal moves before zoom, and why), a renameable list of refusal conditions, zoom clamping to [1x,4x] reported via `clamped`, and a 3s polling behaviour that returns `settled:false` as a non-error. This is unusually rich behavioural disclosure for a mutation tool.

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

Conciseness4/5

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

The core action is front-loaded in the first sentence, followed by preconditions, then behaviour, then return signals — a sensible order. It is dense and long, with a couple of clauses (e.g. the non-16:9 diagnostic aside) that could be trimmed, but nearly every sentence earns its place.

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?

No output schema exists, and the description still documents the returned signals (`clamped`, `settled`) and how to interpret them before a follow-up snapshot. Given the tool's complexity — nine parameters, gimbal+zoom mutation, timed settlement — the definition covers everything an agent needs to call it correctly.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate and largely does: it explains x/y/width/height as the region, the origin constraint on frameWidth/frameHeight, and `margin`'s default of 0.1 and its meaning (backing off the zoom, tighter axis decides). The `camera` parameter and the specific `source` enum meanings are left unexplained.

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 precise verb and resource: 'Frame a region of a frame you just captured: centre the gimbal on it and zoom so the region fills the frame.' It also explicitly distinguishes itself from siblings by naming obsbot_capture_snapshot as the input source and obsbot_aim_at_pixel as its behavioural sibling.

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

Usage Guidelines5/5

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

Explicitly states the precondition (must come from a snapshot, with frameWidth/frameHeight from THE SAME result) and spells out the failure conditions under which the tool refuses. It also points to obsbot_aim_at_pixel as the tool sharing the `source` declaration and refusal semantics, so the agent knows where the alternatives sit.

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

Deploy Server

Other Tools