This server provides full control of OBSBOT Tiny 2 cameras over USB/UVC, without vendor SDK, from any MCP-compatible AI client. Tools are organized into:
Device Management: Enumerate cameras with serials (obsbot_devices), wake/sleep (obsbot_wake, obsbot_sleep), read live status (obsbot_status).
Gimbal Control: Absolute pan/tilt/roll ±150°/±90° (obsbot_gimbal_move), speed-based driving (Windows/macOS only; obsbot_gimbal_move_speed), recenter (obsbot_gimbal_recenter), read position (obsbot_gimbal_position), aim at pixel (obsbot_aim_at_pixel), zoom-to-fit region (obsbot_zoom_to_fit).
Gimbal Presets: List, save, recall, update, rename, delete up to 3 slots (obsbot_preset_*).
Zoom: UVC zoom 1.0–2.0 (obsbot_zoom_uvc), vendor zoom with speed (obsbot_zoom_vendor).
AI Tracking: Enable/disable with modes: normal, upper-body, close-up, headless, lower-body, group, whiteboard, desk, hand (obsbot_ai_track); speed: standard/sport (obsbot_ai_track_speed); face-priority AF toggle (obsbot_focus_face).
Image & Lens: FOV wide/medium/narrow (obsbot_image_fov), HDR toggle (obsbot_image_hdr), autofocus (obsbot_focus_auto) or manual 0–100 (obsbot_focus_manual), auto exposure (global/face) or manual 0–100 (obsbot_image_exposure_auto, obsbot_image_exposure_manual), auto white balance or manual Kelvin (obsbot_image_wb_auto, obsbot_image_wb_manual), adjust brightness/contrast/hue/saturation/sharpness 0–100 (obsbot_image_adjust).
Capture: Snapshot with resolution/quality, supports device/virtual/NDI (obsbot_capture_snapshot), record MP4 with optional duration/audio/path (obsbot_capture_record), live preview (obsbot_capture_preview), stop/list sessions (obsbot_capture_stop, obsbot_capture_list).
Diagnostics (Debug Mode): Raw USB XU probe (obsbot_debug_probe, requires --debug).
Multi‑camera: Optional camera serial parameter on most tools.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@obsbot-mcp recenter the camera gimbal"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A cross-platform Model Context Protocol server that controls an OBSBOT Tiny 2 camera over its standard UVC/USB interface — pan/tilt/roll the gimbal, zoom, AI subject tracking, focus/exposure/white-balance/image controls, HDR and field-of-view, plus snapshot, preview, and recording — without any vendor SDK.
npm install obsbot-mcpRelated MCP server: Robot MCP Server
Add a stdio server entry pointing at the installed binary (or directly at dist/index.js):
{
"mcpServers": {
"obsbot": {
"command": "obsbot-mcp"
}
}
}If you're running from a local checkout instead of an npm install, point command/args at
node and the built entry point instead:
{
"mcpServers": {
"obsbot": {
"command": "node",
"args": ["path/to/obsbot-mcp/dist/index.js"]
}
}
}By default the server advertises only the normal control surface. Pass --debug to additionally
expose the diagnostics surface — the obsbot_debug_probe tool (raw XU byte get/set/query) and the
raw 60-byte status block on obsbot_status:
{
"mcpServers": {
"obsbot": {
"command": "node",
"args": ["path/to/obsbot-mcp/dist/index.js", "--debug"]
}
}
}With the installed binary, use "command": "obsbot-mcp" and "args": ["--debug"].
35 tools on Windows and macOS, 34 on Linux (obsbot_gimbal_move_speed is unavailable there — see
limitations). --debug adds obsbot_debug_probe for
one more. All names below are current as of v0.4.0 — every tool was renamed in this
release and there is no backward-compatible alias; see CHANGELOG.md for the
full old→new mapping if you're updating a caller.
camera selectorEvery camera-addressing tool accepts an optional camera parameter: the target camera's serial
number. Omit it with a single camera attached and nothing changes — this matches the server's
pre-v0.4.0, single-camera behaviour exactly. With more than one camera attached, a call that omits
camera fails with an error naming every attached serial, so you always know what to pass next.
Exempt (no camera parameter, ever): obsbot_devices (enumerates the whole fleet),
obsbot_capture_stop / obsbot_capture_list (address a sessionId, not a device), and
obsbot_debug_probe (operates on the current diagnostics transport). Two more tools honor it only
partially — see Capture below.
Multi-camera support is new in v0.4.0. It's exercised by the unit test suite against fakes; running two physical Tiny 2s at once has not yet been hardware-verified (see Known limitations).
obsbot_devices is the way to discover the serials you pass as camera: it reports each attached
camera's serial (where obtainable — reading it requires briefly opening the camera), name, and
status (available | bound | busy). A camera another process already holds comes back busy
with no serial, since it can't be opened to read one.
Tool | Parameters | Description |
| — | List attached OBSBOT cameras with each one's serial (where obtainable), name, and status ( |
|
| Wake the camera/gimbal (sends |
|
| Sleep the camera/gimbal (sends |
|
| Read the live status block: |
Tool | Parameters | Description |
|
| Move the gimbal to an absolute angle. Positive yaw pans to the camera's left, positive pitch tilts down. Yaw clamped to |
|
| Drive the gimbal at a speed, then auto-stop after |
|
| Recenter the gimbal — drives it to yaw |
|
| Read the gimbal's current absolute |
|
| Point the camera at a pixel from a frame you just captured. Reads the camera's magnification from its own reported state — a discrete FOV mode or a continuous zoom alike — so it needs no FOV or zoom argument and works at any zoom. Refuses while AI tracking is active, when the FOV mode can't be decoded, or when a corrupt zoom reading would resolve to an implausible magnification, and refuses if the camera had to be woken (waking moves the gimbal, invalidating the frame you measured) or if the zoom is still ramping (the frame was captured at a magnification the camera has already left, so wait for the zoom and take a fresh snapshot). |
|
| Frame a region of a frame you just captured: centre the gimbal on it and zoom so the region fills the frame. Same refusal conditions as |
obsbot_capture_snapshot returns the frame as an image plus its width/height, so a model can
locate something in the picture and then point the camera at it:
obsbot_capture_snapshot — look at the frame
obsbot_aim_at_pixel — pass the target's pixel and that frame's dimensions
obsbot_capture_snapshot again — confirm it landed, and repeat if needed
Pass the frameWidth/frameHeight from the same snapshot the pixel came from. Mixing a pixel from
one frame with dimensions from another aims at the wrong place, and nothing can detect it.
The snapshot must be source: "device". obsbot_capture_snapshot can also read from
source: "virtual" or "ndi", which come from OBSBOT Center's own output rather than the camera's
raw stream. Those are framed and cropped by OBSBOT Center, not by this camera's optics, so the
measured field-of-view constants this tool relies on don't describe them — aiming from a virtual or
NDI frame lands in the wrong place with no way to detect it. Only use a device-source snapshot's
pixel and dimensions here.
The tool reads the camera's magnification itself — a discrete FOV mode or a continuous zoom alike
(m = 3*ratio-2, measured on hardware to better than 0.05%) — so there is no FOV or zoom argument to
get wrong, and it works at any zoom. It refuses rather than guessing when AI tracking is on (tracking
drives the gimbal and would fight the aim), when the FOV mode can't be decoded, when a corrupt zoom
reading would resolve to an implausible magnification, or when the camera had to
be woken from sleep (waking moves the gimbal, so the frame you measured no longer matches where the
camera is pointing — take a fresh snapshot and retry).
obsbot_zoom_to_fit extends the same idea from a point to a region: instead of just centring on a
pixel, it also zooms so that region fills the frame.
obsbot_capture_snapshot — look at the frame
Pick a bounding box around whatever should fill the frame (a face, a whiteboard, ...)
obsbot_zoom_to_fit — pass the box (x, y, width, height) and that frame's dimensions
obsbot_capture_snapshot again — confirm the framing, and repeat if needed
It shares obsbot_aim_at_pixel's refusals (AI tracking, undecodable FOV/zoom, a woken camera, a zoom still ramping, a
non-16:9 frame), and adds one of its own: the region must lie within the frame — edges included, so a
region that already IS the full frame is valid — with a positive width and height, or the call refuses
rather than guess what a negative width or an off-frame box was supposed to mean.
margin (default 0.1, i.e. 10%) backs the requested zoom off by that fraction so the region isn't
framed exactly edge-to-edge — some breathing room around it survives small aim/zoom error. The
region's two axes rarely need the same zoom to fill the frame; the tool always picks the smaller of
the two required magnifications, because zooming to the larger one would fill one axis by cropping the
other. The result is clamped to the camera's [1x, 4x] magnification range (reported via clamped) —
a region demanding more zoom than the camera has still gets the closest fit available, rather than
being refused outright.
The gimbal moves before the zoom is commanded. Zoom re-centres what's already in frame but does not keep a specific pixel under the crosshair as it changes — zooming first can push the region's centre out of frame entirely, which would make the subsequent move aim at a pixel that no longer means what it did when the caller measured it.
Zoom is not instantaneous: on this hardware it ramps toward the commanded value rather than jumping to
it, so a status read taken immediately after commanding it can catch it mid-transit (observed:
commanding ratio 1.5 read back partway there before settling). obsbot_zoom_to_fit polls for up to 3
seconds waiting for the zoom to arrive and returns settled:false — not an error — if it didn't. A
frame captured while the zoom is still moving is at an unknown magnification, so check settled
before trusting a follow-up snapshot; a false just means the camera was moving slower than expected,
not that anything failed.
Three on-device preset slots (1–3). Slots are create-once: obsbot_preset_save requires an
empty slot (delete first to reuse one); every other preset tool requires the slot to already be
occupied. Each tool re-reads the slot list after writing and returns a structured { ok:false }
failure if the device didn't land the change.
Tool | Parameters | Description |
|
| Read the three preset slots: occupied/empty, name, and pose in degrees. |
|
| Save the gimbal's current live pose into an empty slot. |
|
| Recall an occupied slot, driving the gimbal to its saved pose. |
|
| Overwrite an occupied slot with the gimbal's current live pose. |
|
| Rename an occupied slot (names over 40 bytes are truncated). |
|
| Delete an occupied slot, freeing it for |
Two tools, not one — they ride different transports (standard UVC vs. the vendor command frame)
and produce different physical zoom at the same commanded ratio, so merging them would silently
change what ratio means. Pick by which behaviour you need.
Tool | Parameters | Description |
|
| Standard UVC zoom: set an absolute zoom ratio, clamped to |
|
| Vendor zoom path with adjustable speed: zoom to a ratio at a chosen speed ( |
Tool | Parameters | Description |
|
| Enable/disable AI tracking and choose the mode: a human framing ( |
|
| Set the tracking-speed preset (Center's Standard/Sport): |
|
| Enable or disable face-priority autofocus. |
Focus, white balance, and exposure each split into a dedicated _auto and _manual tool in
v0.4.0 (previously one tool with a mode parameter) — auto and manual take different parameters, so
splitting them lets each schema say exactly what it needs.
Tool | Parameters | Description |
|
| Set the field of view: wide (86°), medium (78°), narrow (65°). |
|
| Toggle HDR/WDR imaging on or off. |
|
| Enable continuous autofocus. |
|
| Set the focus motor to |
|
| Enable auto-exposure; optional |
|
| Set exposure |
|
| Enable auto white balance. |
|
| Set a colour temperature (clamped to device range). |
|
| Adjust |
obsbot_capture_record and obsbot_capture_preview do not take camera. They select a device
by source (device/virtual/ndi) through ffmpeg/ffplay, not by serial — there is no
serial-to-ffmpeg-device mapping yet. obsbot_capture_snapshot honors camera only for
source:"device"; for source:"virtual"/"ndi" the pixel source is still resolved by device
name, independent of camera.
Tool | Parameters | Description |
|
| Grab one still frame and return it as an image (for framing/lighting/exposure checks). |
|
| Start recording to MP4. Open-ended recordings auto-stop after 60 min; audio uses the OBSBOT mic; defaults to |
|
| Open a live preview window. Returns a |
|
| Stop a recording or preview session (recordings are finalized gracefully). No |
| — | List active recording/preview sessions. No |
--debug only)Tool | Parameters | Description |
|
| RE/diagnostics only — raw XU byte get/set and framed table queries. Advertised only under |
¹ record/preview shell out to ffmpeg/ffplay (install: winget install Gyan.FFmpeg
on Windows, brew install ffmpeg on macOS, apt install ffmpeg on Linux). snapshot does not
need ffmpeg — it grabs the frame through the native helper.
Windows x64 — supported today. The native helper is built from source in native/windows/
(CMake + MSVC); the published npm package ships a prebuilt binary so end users need no toolchain.
Linux x64 — supported from v0.2. The native helper is in native/linux/ (CMake + GCC);
it uses V4L2 for standard UVC controls (zoom, focus, exposure, pan/tilt, white balance,
image controls) and UVCIOC_CTRL_QUERY for vendor Extension Unit commands (gimbal speed/AI
tracking, wake/sleep, HDR, FOV). Snapshots capture a MJPEG or YUYV frame via V4L2 mmap streaming
and encode to JPEG using libjpeg. The linux-x64 prebuilt binary ships with the published npm
package. Build dependencies: build-essential cmake libjpeg-dev libv4l-dev.
Gimbal position reads (obsbot_gimbal_position) reflect the last-commanded value, not live
in-flight position — see "Linux gimbal position feedback"
below for why, and what would fix it.
macOS 14+ (Apple Silicon and Intel) — supported. The native helper is in native/macos/
(Objective-C + IOKit/AVFoundation). It uses IOKit USB control transfers for both standard
UVC controls and vendor Extension Unit commands, and AVFoundation for enumeration and snapshots.
Both darwin-arm64 and darwin-x64 prebuilt binaries ship with the published npm package
(darwin-x64 also covers Apple Silicon running Node under Rosetta, where process.arch reports
x64). macOS 14 is the floor because the helper uses AVCaptureDeviceTypeExternal; the build
pins -mmacosx-version-min so the binary does not inherit the build machine's OS as its
minimum.
Note on macOS specifically: UVCAssistant (a DriverKit system extension) owns the camera's UVC
interfaces exclusively, so USBInterfaceOpen — and even USBInterfaceOpenSeize — fail with
kIOReturnExclusiveAccess. The helper therefore opens the USB device, which is not locked, and
issues UVC control requests on its default control endpoint. This coexists with UVCAssistant:
the camera keeps working as a normal webcam while under control, so no driver-replacement step
is needed.
cd native/linux
mkdir build && cd build
cmake ..
make -j$(nproc)
make install # copies to native/prebuilt/linux-x64/obsbot_gimbal_position on Linux reports the last position obsbot_gimbal_move/
obsbot_gimbal_recenter commanded — not a live, in-flight reading. Hardware testing (2026-07-21)
confirmed the OBSBOT Tiny 2's CT_PANTILT_ABSOLUTE control genuinely tracks live position — a raw
USB read of that same control, bypassing the kernel, showed a real slew progressing in real time.
The reason plain V4L2 (VIDIOC_G_CTRL) never sees that is that uvcvideo caches the control's
value and serves the cache instead of re-querying the device (confirmed via
VIDIOC_QUERY_EXT_CTRL, which reports no V4L2_CTRL_FLAG_VOLATILE). The driver invalidates that
cache when the device sends a UVC Control Change interrupt — which this camera's firmware never
does, and never advertises support for.
Getting a genuinely live reading through V4L2 requires briefly detaching the kernel driver from the camera's control interface and reading the control directly over raw USB — but detaching that interface (even briefly, even without writing anything) breaks any concurrent video capture on this device: streaming and control share one kernel-managed USB function, so pulling the driver off one takes both down together. That makes a libusb-based workaround incompatible with anything actually using the camera as a webcam at the same time, which ruled it out as a shipped default.
A kernel patch has been submitted upstream (media: uvcvideo: query pan/tilt position from the device on every read,
July 2026 — awaiting review, not merged). It marks CT_PANTILT_ABSOLUTE volatile so the driver
queries the device on every read; verified on this hardware to track a live slew through plain
VIDIOC_G_CTRL, concurrently with streaming. If it is accepted, obsbot_gimbal_position becomes
live on Linux with no code changes needed here. Until it ships in a kernel near you:
obsbot_gimbal_move and obsbot_gimbal_recenter work normally — hardware-verified,
repeatedly, via direct V4L2 VIDIOC_S_CTRL writes. Their target values are known and clamped
before being sent, so they can't exceed the gimbal's mechanical range regardless of the missing
feedback.
obsbot_gimbal_move_speed is not available on Linux (hidden from the tool list entirely,
not just refused at runtime). A speed×duration burst has no target position to clamp — without a
live reading to confirm where the gimbal actually is, there's no way to bound it against the
mechanical limits before it gets there. It remains available on Windows/macOS.
make -C native/macos # -> native/prebuilt/darwin-arm64/obsbot-helperRequires the Xcode command line tools. CMake works too (cmake -S native/macos -B native/macos/build && cmake --build native/macos/build), which is what CI uses.
What has actually been exercised against hardware, and what hasn't:
Platform | Status |
| Hardware-verified — mid-session disconnect recovery ( |
| Hardware-verified — gimbal absolute moves and recenter via V4L2 (20 consecutive moves with a live preview running), and the arc-second scaling fix confirmed by physical swing. Gimbal position is not live and |
| Hardware-verified — control, gimbal movement and per-axis position readback, zoom, snapshot, USB vid/pid candidacy, serial readback and serial-keyed binding, single-owner IPC coordination, helper-death recovery, and unaided recovery from an unplug/replug, on a real Tiny 2 |
| Build-verified only — compiles with the right architecture and deployment target, never executed |
The Intel (darwin-x64) helper has never been run. No Intel Mac was available to test it. It
cross-compiles cleanly and is packaged, but nothing has confirmed it talks to a camera. It also
covers Apple Silicon running Node under Rosetta, where process.arch reports x64 — likewise
untested. Reports from Intel users are welcome.
macOS 14 or newer is required, and macOS runtime is verified on 26.5 only. The helper uses
AVCaptureDeviceTypeExternal (macOS 14+), so the build pins -mmacosx-version-min=14.0. The
binary will load on 14 through 25, but behavior there is untested — in particular the UVC
control path relies on UVCAssistant holding the camera's UVC interfaces while leaving the USB
device itself openable. That is how current macOS behaves; older releases are unconfirmed.
The first snapshot on macOS raises a camera permission prompt. The helper is a plain CLI tool with no bundle identifier, so macOS attributes camera access to whichever app spawned it — your MCP client — and that app is named in the prompt and holds the grant. Approve once; the grant survives helper updates, since it is keyed to the client rather than to the helper's signature.
AI tracking overrides manual gimbal moves. When AI tracking is active (the Tiny 2's default
on wake), a commanded pan/tilt executes and is then pulled back to the tracked subject —
obsbot_gimbal_position shows the yaw/pitch move out and decay back to rest. This is the camera's
behaviour, not a bug: turn tracking off for unopposed manual control.
The camera may not enumerate through a USB hub or dock. A Tiny 2 connected through a USB-C
dock was invisible to ioreg and system_profiler entirely — not just to this server. If
obsbot_devices comes back empty, try a direct connection before assuming a software fault.
Only the OBSBOT Tiny 2 is supported. On Windows and macOS candidacy is gated on the Remo USB
vendor ID plus a known-model product ID (0x3564/0xFEF8), so no other model is detected at
all — and a name-matching software source, such as the "OBSBOT Virtual Camera" that OBSBOT Center
registers, is rejected because it reports no vid/pid. Linux still matches by name, because its
helper does not report vid/pid yet, so a different OBSBOT may be found there — but the vendor
command set is Tiny 2 specific either way. (On macOS the virtual camera cannot appear at all: the
helper enumerates USB devices through the IORegistry, which a software camera never enters.)
The vendor reply mailbox is unreliable for several seconds after a replug. On 2026-07-21 a
Tiny 2 was seen returning only the host's own echoed request frame from the vendor reply mailbox
(XU selector 2) — magic byte 0xaa cleared to 0x00, every other byte identical — for a
continuous 3.2 s. readSerial() threw, bind() found no serial, and every tool needing a bound
camera failed with "no OBSBOT camera found" while the device was plainly healthy: correct
vid/pid, opened fine, XU node 2, live status block on selector 6.
That was unexplained for a while. It is now reproducible: immediately after a USB
re-enumeration. Polling readSerial every 50 ms across a replug failed 22 times in 80 attempts
spread over the first 14 s, against 0 in 120 in steady state; the first read after arrival showed
exactly the echoed-request signature above, and later failures showed the reply slot populated
but with its magic byte still zeroed. Ruled out as causes: stale per-process device state (the
same long-lived helper read a brand-new uniqueID cleanly at t+49 ms), re-opening the device
(0/40 either way), and the per-transport sequence counter restarting at 1 (0/80).
Consequence for callers: a bind attempted in the first seconds after a replug can fail even
though the camera is fine. Retrying works. The arrival-driven re-bind now retries on a bounded
ladder for this reason, and a readSerial failure reports what the mailbox actually held
(echoed request / unparseable / a reply to another request) rather than only "no valid reply".
Ruled out earlier and still ruled out: reply latency (polled 3.2 s), the wrong extension unit
(the VideoControl interface exposes exactly one, bUnitID 2), the wrong wLength (every XU
selector is 60 bytes by GET_LEN), the reply arriving on another selector (1–19 swept), camera
sleep state, and contention from OBSBOT Center.
Recovery after a replug is proactive, but not in every case, and it differs by platform.
The server subscribes to OS camera arrival/removal events, so in the common case a replugged
camera re-binds itself with no tool call — obsbot_devices reports it bound again on its own.
Every cell below is hardware-measured:
scenario | macOS | Windows | Linux |
same-port replug | proactive | proactive | next tool call |
different-port replug | proactive | next tool call | next tool call |
Where it says "next tool call", nothing is stranded — the call that follows detects the stale binding, prunes it and re-binds. It costs one failed call, which is exactly how every platform behaved before these events existed. The Windows difference comes from its arrival filter requiring a path it has already enumerated, which is also what stops the Tiny 2's audio interface from being reported as a second camera; macOS has no equivalent problem because it re-binds by serial and ignores the path. Linux emits no bus events at all yet.
Note the interaction with the mailbox entry above: a re-bind attempted immediately after a replug can still lose the first attempt, so the server retries on a short bounded ladder.
Two-camera operation is not yet hardware-verified. The camera selector and the
per-camera device registry are covered by the unit test suite against fake transports; running
two physical Tiny 2s attached at once has not been confirmed on real hardware (a second unit
wasn't available). Single-camera use is unaffected either way.
Linux gimbal position feedback is not live, and obsbot_gimbal_move_speed is unavailable
there as a result. See "Linux gimbal position feedback is not live"
above — a kernel patch fixing this at the source has been submitted upstream
(July 2026, awaiting review). obsbot_gimbal_move and
obsbot_gimbal_recenter are unaffected; both are hardware-verified to work normally.
obsbot_aim_at_pixel is affected — it depends on a live pose reading to compute the aim, the
same way obsbot_gimbal_position does.
obsbot_zoom_vendor's ratio scale doesn't match obsbot_zoom_uvc's at the same ratio. A
hardware snapshot comparison at ratio: 2.0 showed the vendor path framed tighter than the UVC
path. Whether the vendor-side ratio encoding is off by a scale factor, or the two zoom controls
simply have different physical ranges, isn't determined yet — one comparison isn't enough to
tell. Tracked separately; use obsbot_zoom_uvc if you need the ratio to land exactly.
This project speaks the camera's USB protocol directly through the OS's standard UVC driver stack and
does not use, link, bundle, or ship any vendor SDK. See PROTOCOL.md for the
protocol reference (frame format, checksum, command table).
The camera exposes two independent control surfaces, both reachable through the OS's standard UVC (USB Video Class) driver stack — this project never talks to the USB device directly, so the OS keeps mediating access and the camera remains usable as a normal webcam at the same time commands are sent:
Standard UVC controls — zoom (CT_ZOOM_ABSOLUTE), focus and exposure (IAMCameraControl),
gimbal position readback (UVC Pan/Tilt), and the image controls plus white balance
(IAMVideoProcAmp) — are the camera's built-in UVC properties, driven via DirectShow on Windows.
Vendor commands — gimbal moves, recenter, wake/sleep, AI tracking, HDR, and field of view —
are sent through the camera's UVC Extension Unit, driven via IKsControl::KsProperty against the
XU's topology node on Windows.
Both are issued through a small native helper process (obsbot-helper.exe on Windows, obsbot-helper
on Linux) that the Node server spawns and talks to over a line-delimited JSON-RPC protocol on
stdin/stdout. The helper is the only platform-specific piece; the codec (frame encoding, CRC-16/USB
checksum, command table), transport abstraction, device manager, and MCP tool definitions are all pure
TypeScript/JavaScript and shared across platforms.
scripts/e2e.mjs drives the built stack (dist/) against a physically connected camera: it wakes the
device, zooms in, pans the gimbal, recenters, zooms back out, and puts the camera to sleep, with a short
pause and console log before each step so a human can watch it happen. This moves the physical gimbal —
only run it under supervision:
npm run build
node scripts/e2e.mjsTwo traps make it easy to test the wrong thing and believe the result. Both cost real time on 2026-07-25.
Rebuilding and reloading is not enough — kill stale server processes first. The MCP server runs
from dist/, so a source change is invisible until npm run build. But reloading the server in your
MCP client does not guarantee your new code executes: this project coordinates concurrent clients
by electing a single owner process (see IPC-DESIGN.md), and a reload spawns a new client that
forwards its tool calls to whatever owner is already running. An orphaned server from a previous
session stays the owner, so the new process advertises its own up-to-date tool list while every call
is executed by old code.
That failure is deceptive rather than loud: a newly added tool appears in the tool list and can be called, but behaves like the old build. Two reloads in a row will not fix it. Check for orphans before concluding anything:
# Windows
Get-CimInstance Win32_Process -Filter "Name='node.exe'" |
Where-Object { $_.CommandLine -like "*Obsbot*" } |
Select-Object ProcessId, CreationDate# Linux / macOS
pgrep -af "obsbot.*dist/index.js"Kill everything older than your build, then reload. The cheapest positive confirmation is to call a
tool whose output changed — obsbot_status gaining a field, say — rather than one whose
description changed, since descriptions come from the new process either way.
Frame rate selects the field of view, so the preview shows less than snapshots. At 1920×1080 this
camera has two different windows onto the sensor and the frame rate picks between them — not the
codec. Measured at one pose and one zoom: MJPEG@30 vs YUYV@30 came out at scale 1.00001 over 2382
inliers, i.e. the same field to within a fifth of a pixel, while MJPEG@60 is a 1.214× crop of both.
obsbot_capture_preview pins 60fps for smooth motion, so it shows ~21% less of the room than
obsbot_capture_snapshot, which negotiates 1080p30. Framing by eye in the preview and then aiming at a
pixel from a snapshot will not agree. The geometry constants describe the 30fps field. Any measurement
you make must state pixel format and frame rate; neither a resolution nor a codec alone identifies
the field.
A preview holds the camera stream, so snapshots fail while one is open. obsbot_capture_preview
and obsbot_capture_snapshot both need the device stream, and on Windows the second one gets
Camera is in use by another application. This matters for the aim loop above, which is
snapshot → aim → snapshot: stop the preview around each snapshot, or work without one. Gimbal control
is unaffected — it uses control transfers, not the stream — so obsbot_aim_at_pixel itself works fine
with a preview running. The error text suggests source: "virtual" or "ndi" as a workaround. That is safe for looking,
and safe for aiming only if the feed is an unmodified pass-through of the camera — declare it with
the source parameter on obsbot_aim_at_pixel / obsbot_zoom_to_fit and read the note it returns.
A compositor that rescales or letterboxes the frame silently invalidates the geometry.
Point the camera at a specific pixel in a frame you just captured. Give the pixel's x/y and the frameWidth/frameHeight from THE SAME obsbot_capture_snapshot result — mixing a pixel from one frame with dimensions from another aims at the wrong place and cannot be detected. source DECLARES which feed the frame came from (default device); it cannot be inferred from the pixels. A virtual or ndi frame is accepted, but only aims correctly if that feed is an unmodified pass-through of the camera — a compositor's rescale or letterbox is invisible in the picture and silently wrong here — so a non-device declaration comes back with that assumption stated. Takes no field-of-view or zoom argument: it reads the camera's magnification from its reported state, a discrete FOV mode or a continuous zoom alike, so it works at any zoom. Refuses when AI tracking is active (tracking moves the gimbal itself and would fight the aim), when the FOV mode can't be decoded, or when a corrupt zoom reading would resolve to an implausible magnification, so it never aims on an assumption it cannot check. If the camera was asleep, waking it moves the gimbal and invalidates the frame you measured, so the call refuses instead of aiming on stale geometry — take a fresh snapshot and retry. Returns clamped:true if the target was outside the gimbal's range; the camera still moves, to the nearest reachable pose. Refuses (ok:false) instead of moving when the pixel lies past vertical from the current pose — reachable only by an "over the top" rotation that would swing the camera toward the opposite side of the room, not toward the target; tilt toward the pixel first, then re-aim.
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| camera | No | ||
| source | No | device | |
| frameWidth | Yes | ||
| frameHeight | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It does so thoroughly: it reads the camera's magnification from reported state, refuses instead of aiming on uncheckable assumptions, returns clamped:true and still moves when target is out of range, refuses with ok:false for over-the-top rotations, and invalidates stale geometry if the camera was asleep. This is exceptionally transparent about side effects and failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but nearly every sentence earns its place by adding a caveat, refusal condition, or side-effect disclosure. The first sentence front-loads the primary purpose. The main weakness is that it is a dense wall of text with multiple embedded clauses, which could be easier to scan with better structuring.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the absence of an output schema, and no annotations, the description covers an impressive amount: prerequisites, refusal conditions, return flags (clamped, ok:false), and the virtual/ndi pass-through assumption. It does not specify the full shape of a successful response or explain the 'camera' parameter, so it is not fully complete, but it is close.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It explains x/y as pixel coordinates, emphasizes that frameWidth/frameHeight must come from the same snapshot, and describes the source enum with its default and pass-through caveat. However, the optional 'camera' parameter in the schema is never addressed, leaving one parameter under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Point the camera at a specific pixel in a frame you just captured.' It clearly distinguishes this from sibling gimbal/zoom tools by targeting a pixel coordinate rather than angles, FOV, or zoom, and further differentiates itself by noting it takes no FOV/zoom argument.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use and when-not-to-use guidance: use coordinates and dimensions from the same obsbot_capture_snapshot result, declare the source, and only use virtual/ndi feeds that are unmodified pass-through. It also lists refusal conditions (AI tracking active, undecodable FOV, corrupt zoom, camera asleep, target past vertical) and tells the agent how to recover: take a fresh snapshot after wake, or tilt toward the pixel before re-aiming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enable or disable AI tracking and choose the mode. When enabled the camera follows the subject; disabling stops tracking. mode is either a human framing (normal | upper-body | close-up | headless | lower-body) or a standalone scene mode (group | whiteboard | desk | hand); scene modes imply enabled:true. After writing, the tool polls the status block until the mode settles and returns { verified, matched } — the aiMode the device actually landed on (matched:false means no subject was being tracked, so the mode could not take effect yet).
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | normal | |
| camera | No | ||
| enabled | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses polling behavior after writing, the return value with verified and matched fields, and clarifies that scene modes set enabled to true. No annotations are provided, so the description adequately covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, starting with the core action, then elaborating on mode semantics, and ending with polling behavior. It is not overly long but could be slightly more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters and no output schema, the description covers the main action, mode details, and return value. It lacks mention of prerequisites or error cases, but is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to mode by explaining human framing vs scene modes and the implication on enabled. However, the camera parameter is not explained. Schema coverage is 0%, so the description provides significant value but misses one parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool enables or disables AI tracking and selects the mode. It mentions that the camera follows the subject and distinguishes from sibling tools like obsbot_ai_track_speed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to control AI tracking) and notes that scene modes imply enabled:true. It does not explicitly exclude alternatives, but provides enough context for proper use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the AI tracking-speed preset (OBSBOT Center's Standard/Sport). speed: standard (slower follow) | sport (snappier follow).
| Name | Required | Description | Default |
|---|---|---|---|
| speed | Yes | ||
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It states the action (set speed) but omits side effects, required system state (e.g., tracking must be active), or whether changes are persistent. The camera parameter is also undocumented in behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by a brief clarification of the enum values. No unnecessary words, front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the core function is explained, the omission of the camera parameter and lack of output schema leave the tool's full behavior partially undefined. For a simple setter, it is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds valuable meaning for the speed parameter ('slower follow' vs 'snappier follow') beyond the enum values. However, the camera parameter is not mentioned at all, leaving its purpose unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets the AI tracking-speed preset, with explicit enumeration of the two options (standard/sport) and their meanings. It is specific and distinguishes from sibling tools like obsbot_ai_track.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, or when to choose standard vs. sport. The description implies use for adjusting tracking speed but lacks context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active recording/preview sessions (id, kind, source, output path, start time).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It implies read-only behavior by stating 'list', but does not explicitly confirm no side effects or require any prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence that includes all key elements: action, resource, and returned fields. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters or output schema, description adequately specifies what the tool returns. Could clarify what 'active' means or handle empty results, but sufficient for a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters and schema coverage is 100%. Baseline for 0 parameters is 4; description does not add parameter info since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'List' and resource 'active recording/preview sessions', specifying the fields returned. Immediately distinguishes from sibling tools like obsbot_capture_stop or obsbot_capture_preview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives provided. However, the simplicity of the tool and absence of similar list tools among siblings makes the context clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a live preview window of the camera (for the user to watch). NOTE: before calling, ensure the camera is focused (call obsbot_focus_auto for autofocus) unless otherwise directed. source: device|virtual|ndi. Returns a sessionId for obsbot_capture_stop.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | device |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the preview window opening and return of sessionId, but does not detail side effects, blocking behavior, or resource impacts. No annotations to supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus a note, front-loaded with the core action, no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter and no output schema, description covers return value, prerequisite, and source options; reasonably complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, description mentions the source parameter with its enum values but does not elaborate on each option's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (open a live preview window) and distinguishes from siblings like obsbot_capture_snapshot and obsbot_capture_stop.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisite (call obsbot_focus_auto first) and lists source options, but does not explicitly state when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start recording the camera to an MP4 (for the user). durationSec optional (open-ended recordings auto-stop after 60 min); audio defaults to on (the OBSBOT mic); outputPath optional (defaults to ~/Videos/OBSBOT on every platform, including macOS, where that is NOT the usual ~/Movies). NOTE: before calling, ensure the camera is focused (call obsbot_focus_auto for autofocus) unless otherwise directed. source: device|virtual|ndi. Returns a sessionId for obsbot_capture_stop.
| Name | Required | Description | Default |
|---|---|---|---|
| audio | No | ||
| source | No | device | |
| outputPath | No | ||
| durationSec | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full disclosure burden and does it well: it reveals the 60-minute auto-stop for open-ended recordings, that audio is on by default from the OBSBOT mic, the cross-platform outputPath default including the macOS quirk, and the returned sessionId. These are exactly the non-obvious behaviors an agent needs before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded: the core action is in the first clause, and the parenthetical defaults and platform caveat come after. Some punctuation is run-on, but each clause adds operational value rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, this covers the essentials: what it does, defaults, limits, prerequisite focusing step, and return value. An agent could invoke it correctly and know what to expect and how to stop it afterward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates by explaining durationSec's open-ended behavior, audio's default and source, outputPath's default location, and the source enum values. Only 'source' semantics are thin beyond the enum list, but the schema already enumerates valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and object: 'Start recording the camera to an MP4', which clearly distinguishes it from sibling capture tools like obsbot_capture_snapshot or obsbot_capture_preview. It also grounds the tool's role by noting it returns a sessionId used by obsbot_capture_stop, making its place in the workflow explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete precondition: ensure the camera is focused before calling, and names obsbot_focus_auto as the way to satisfy it, with an exception ('unless otherwise directed'). It doesn't explicitly contrast with alternatives (e.g., when to choose snapshot vs record), but the recording target and MP4 context make the intended situation clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Grab one still frame from the camera and return it as an image (for you to see and for framing/lighting/exposure checks). resolution is the longest edge in pixels, 256-1920, default 640 — larger images cost proportionally more tokens, so ask for more only when you need the detail. NOTE: before calling, ensure the camera is focused (call obsbot_focus_auto for autofocus) unless otherwise directed. source: device (default) | virtual | ndi. If the camera is in use by another app, returns a message instead of an image.
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No | ||
| source | No | device | |
| quality | No | ||
| settleMs | No | ||
| resolution | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses token cost scaling with resolution, source options, and conflict behavior. Missing details on output format and blocking nature, but adequate for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with purpose first, then resolution note, prerequisite, source list, and failure scenario. Each sentence adds value. Could integrate source line more smoothly, but overall concise and organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, 0% schema coverage, no output schema, and no annotations, the description covers purpose, resolution, prerequisite, and failure mode but omits quality, settleMs, camera, and output format. Adequate for basic use but lacks completeness for nuanced agent decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. Only resolution and source are explained; parameter quality, settleMs, and camera are not described. Quality and settleMs have no explanation of their effect, and camera accepts any string without guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Grab one still frame from the camera and return it as an image' with a specific verb and resource. It distinguishes from siblings like obsbot_capture_preview (likely video preview) by focusing on still frame capture.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisite to ensure camera is focused via obsbot_focus_auto. Mentions source options (device/virtual/ndi) and a failure mode when camera is in use. Lacks explicit contrast with alternatives like obsbot_capture_preview, but the still frame vs preview distinction is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a recording or preview session by its sessionId. Recordings are stopped gracefully so the MP4 finalizes correctly.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that recordings are 'stopped gracefully so the MP4 finalizes correctly,' indicating safe termination. However, it does not describe what happens to preview sessions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no redundant information. Every word is necessary and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, no output schema), the description covers the essential purpose and a behavioral note. It could mention that the session must be active or where to get the sessionId, but overall it's fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It only says 'by its sessionId' without explaining what a sessionId is or how to obtain it, adding minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (stop) and resource (recording or preview session), and specifies the method (by sessionId). It distinguishes from sibling capture tools like capture_snapshot or capture_preview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives (e.g., when to stop vs. capture_snapshot), nor does it mention prerequisites like an active session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List attached OBSBOT-compatible cameras. Each entry is { serial?, locationId?, name, status, reason? }: serial is the value to pass as camera to any camera-addressing tool (present where obtainable — reading it requires briefly opening the camera); status is available (free to bind), bound (already opened by this process), or busy (could not be opened and identified, so it can't be targeted here — usually another process holds it, but it also covers a camera that opened yet would not answer). On a busy entry, reason carries the underlying error and distinguishes those cases.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral details: reading serial requires opening the camera, status meanings and edge cases (busy with reason), and the distinction between availability conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, then detailed structure explanation. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive coverage of return fields, including serial absence, status values, and error reasons. Complements lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description adds no parameter info; baseline 4 applies as per rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('attached OBSBOT-compatible cameras'), and differentiates from sibling tools like 'obsbot_status' by focusing on device enumeration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that the 'serial' field is needed for camera-addressing tools, implying a prerequisite relationship, but does not explicitly state when not to use this tool or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enable continuous autofocus.
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it only states the immediate effect. It does not mention whether this overrides manual focus, whether it persists across sessions, or what observable side effects occur on the camera.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four words with zero filler, and the core action is immediately front-loaded. It is efficiently concise, though it verges on being too sparse to serve as a complete definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no annotations and no output schema, the description leaves important gaps: the meaning of the camera parameter and the behavioral implications of enabling continuous autofocus are unaddressed. It identifies the intent but is insufficient for reliable autonomous invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'camera' is an undocumented string with 0% schema description coverage, and the description never mentions it. An agent has no way to know what values are acceptable, what the parameter identifies, or whether it is safe to omit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Enable continuous autofocus') on a specific resource, making the tool's intent immediately understandable. It distinguishes itself from obsbot_focus_manual by the word 'continuous', though it does not explicitly name or contrast itself with siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like obsbot_focus_manual or obsbot_focus_face. There is no context for when continuous autofocus is appropriate or why an agent would select this over other focus-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enable or disable face-priority autofocus.
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No | ||
| enabled | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so description carries full burden. It fails to disclose behavioral traits like toggling behavior, effects on other settings, or state requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but lacks structure or additional context. It is front-loaded but too sparse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no description of return values or side effects. For a boolean toggle, missing information about toggling behavior and camera parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and description does not explain the 'camera' parameter (optional string). The 'enabled' parameter is self-explanatory, but the undocumented parameter is a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb (enable/disable) and resource (face-priority autofocus), distinguishing it from siblings like obsbot_focus_manual.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., manual focus). No context on prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the focus motor to position (0-100, near→far), mapped onto the device range.
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No | ||
| position | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral disclosure. It mentions mapping onto the device range but does not state if the action is instant, reversible, or requires specific device state. No side effects or dependencies are noted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no filler, directly conveys the core action and range. Efficiently structured with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity (2 params, no output schema), the description omits clarification for the 'camera' parameter and lacks behavior details. Not sufficiently complete for an agent to use correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description only explains the 'position' parameter (range and mapping), but does not clarify the 'camera' parameter, which is a string with no format guidance. The agent may not know how to specify the camera.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (set), resource (focus motor), and range (0-100, near to far), distinguishing it from sibling tools like obsbot_focus_face which is presumably auto/manual focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., obsbot_focus_face), no prerequisites or exclusions mentioned. The name implies manual control, but explicit advice is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move the gimbal to an absolute yaw/pitch angle (degrees); positive yaw pans to the camera's left, positive pitch tilts down. Yaw is clamped to [-150,150], pitch to [-90,90]. Absolute positioning (1:1 degrees), verified on hardware.
| Name | Required | Description | Default |
|---|---|---|---|
| yaw | Yes | ||
| roll | No | ||
| pitch | Yes | ||
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses clamping ranges, direction conventions, and hardware verification. However, it omits error handling details and potential side effects (e.g., state changes).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first defines action and conventions, second adds ranges and verification. No filler, well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite missing parameter descriptions and no output schema, the description covers the core behavior adequately. Minor gaps like asynchronous completion or out-of-range behavior prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains yaw and pitch (ranges, direction) but does not mention the 'roll' and 'camera' parameters, leaving key semantics undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('move the gimbal'), the resource (gimbal), and the mode ('absolute yaw/pitch angle'). It specifies direction conventions and distinguishes from sibling tools like obsbot_gimbal_recenter by emphasizing absolute positioning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for absolute moves but lacks explicit guidance on when to prefer this over alternatives like presets or recentering. No when-not or alternative comparisons are provided, though the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the gimbal's current absolute yaw/pitch in degrees (positive yaw = camera's left, positive pitch = down) via the standard UVC Pan/Tilt controls. This is a live hardware readout accurate to ±1°, reported rounded to 2 decimal places (finer digits would be noise, not precision): it is valid during a move as well as after one, and reflects motion the host did not command (speed moves, recenter, tracking).
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it excels: it discloses accuracy (±1°), rounding behavior, validity during moves, and that it reflects externally-initiated motion. This gives the agent a nuanced model of what the tool does beyond a simple 'getter.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loads the core purpose before diving into precision details. The parenthetical about noise versus precision is slightly verbose but still informative; overall it is efficiently organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, yet the description never specifies the return format (e.g., field names or a JSON structure), leaving an agent uncertain about how to interpret the result. The undocumented 'camera' parameter further reduces completeness, so important information for invoking the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter ('camera', a string) with 0% description coverage, and the description never mentions the camera parameter at all. Since the schema provides no meaning beyond its type, and the description does not compensate, an agent has no idea what to pass for this parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read') and resource ('the gimbal's current absolute yaw/pitch in degrees'), with units and sign conventions. It is clearly distinguished from sibling tools like obsbot_gimbal_move and obsbot_gimbal_recenter, which perform actions rather than read state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage for querying the current gimbal position and even notes it reflects motion from external actions like speed moves, recenter, and tracking, which helps an agent know it is useful for live monitoring. However, it never explicitly says when not to use it or contrasts it with move/recenter, so it falls just short of a fully explicit routing guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recenter the gimbal — drives it back to yaw 0 / pitch 0 (level and facing forward). Returns as soon as the command is sent: the gimbal may still be moving, so poll obsbot_gimbal_position if you need to know it has arrived.
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses the async nature (command returns before movement finishes) and recommends polling. It does not mention permissions or side effects, but the disclosed behavior is sufficient for safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and every word adds value. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the action, target orientation, and async behavior with a polling suggestion. However, it omits documentation of the 'camera' parameter, which is a notable gap. For a simple tool with no output schema, it is otherwise adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one optional parameter 'camera' (type string) with no description. The tool description does not explain this parameter at all, leaving its purpose unclear. With 0% schema coverage, the description should compensate but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool recenters the gimbal to yaw 0/pitch 0 (level and facing forward). It uses a specific verb 'recenter' and identifies the resource, distinguishing it from sibling tools like obsbot_gimbal_move or presets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the command returns immediately and the gimbal may still be moving, advising to poll obsbot_gimbal_position for arrival. It gives clear context for when to use and suggests an alternative, though it does not explicitly state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adjust a standard image control: control is brightness | contrast | hue | saturation | sharpness | gain | backlight-compensation; level 0-100 is mapped onto the device's supported range for that control. Standard UVC (IAMVideoProcAmp), no auto. NOTE: gain and backlight-compensation are NOT implemented on the Tiny 2 — it reports them as zero-length controls — so they are refused with an error rather than silently doing nothing. The other five work.
| Name | Required | Description | Default |
|---|---|---|---|
| level | Yes | ||
| camera | No | ||
| control | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses standard UVC protocol, no auto, and device-specific failures for some controls. But does not mention persistence, atomicity, or prerequisites (e.g., camera must be active). With no annotations, this is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences. First sentence defines purpose, second adds context, third and fourth provide critical caveats. No redundancy, optimally front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers tool purpose, controls, range, mapping, and device-specific limitations. Lacks information about return values or persistence, but for a simple adjustment tool this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond schema: explains control enum values implicitly (listed), level range is mapped to device range, and notes that gain and backlight-compensation may fail. Camera parameter is not explained, but overall compensates for 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool adjusts a standard image control (brightness, contrast, etc.) with a level 0-100, listing the controls and specifying the mapping to the device's range. This distinguishes it from sibling tools like exposure controls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly indicates manual adjustment (no auto) and provides device-specific guidance about unimplemented controls (gain, backlight-compensation on Tiny 2), warning they will error. However, lacks explicit when-to-use/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enable auto-exposure. Optional priority 'global' | 'face' selects the metering region (face-priority meters for a detected face). Uses the proprietary V3 frame protocol (CAM_SET_EXPOSURE_TINY2, which carries mode and value in one command) because the standard UVC/IAMCameraControl V4L2 path is a stub on the Tiny 2.
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No | ||
| priority | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the proprietary protocol and why standard paths are avoided, providing useful behavioral context. Without annotations, it carries the transparency burden well, though missing details on side effects or auth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main function, no unnecessary words. Efficiently uses space for essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides good context for a simple tool, including protocol details. Lacks explanation of the 'camera' parameter, but overall adequate given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning to the 'priority' parameter by explaining the metering region options and face detection. The 'camera' parameter is not explained, but schema coverage is 0% and description partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool enables auto-exposure and describes the optional priority parameter for metering region, distinguishing itself from the sibling obsbot_image_exposure_manual.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for auto-exposure scenarios via the sibling manual tool, but lacks explicit guidance on when to use this tool versus alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set exposure level 0-100 (0 darkest → 100 brightest), mapped onto the device's exposure range. Also returns raw: the device-native exposure value the level mapped to, for diagnostics — level is the number to reason with. Uses the proprietary V3 frame protocol (CAM_SET_EXPOSURE_TINY2, which carries mode and value in one command) because the standard UVC/IAMCameraControl V4L2 path is a stub on the Tiny 2.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | ||
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses level mapping and raw return value, and explains the proprietary protocol. However, missing side effects, persistence, error behavior, and prerequisites (e.g., camera must be connected).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main action and mapping. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains level and return, but misses explanation of camera parameter, error handling, and relationship to auto mode. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The 'level' parameter is well explained (0-100 mapping). The 'camera' parameter is not described at all, leaving ambiguity about its value and purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets exposure manually with a normalized level (0-100) mapped to the device's range, and distinguishes it from automatic exposure and other image adjustments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like auto exposure or general image adjust. The protocol note is technical but doesn't clarify usage context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the field of view. fov: wide (86°) | medium (78°) | narrow (65°).
| Name | Required | Description | Default |
|---|---|---|---|
| fov | Yes | ||
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It discloses the angle values for each FOV option, which is useful behavioral info, but does not mention side effects, permissions, or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no unnecessary information. It is front-loaded with the purpose and fits within a single line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, and the presence of an undocumented 'camera' parameter, the description is insufficient for full understanding. It omits behavioral details and parameter explanation for one parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description adds meaning for the 'fov' parameter by listing angle values, but provides no info about the optional 'camera' parameter, leaving it undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets the field of view, with a specific verb and resource. It does not explicitly differentiate from siblings, but the function is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists the available FOV options with degrees, giving implied usage context, but lacks explicit guidance on when to use this tool versus alternatives or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Toggle HDR/WDR imaging on or off.
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No | ||
| enabled | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral transparency. It merely says 'toggle on or off' without disclosing side effects, required permissions, or what changes occur during the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (5 words), which makes it concise but under-specified for a tool with parameters. It could be more informative without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the existence of sibling tools, the description lacks explanation of HDR/WDR concepts and the impact of toggling. It is insufficient for an agent to fully understand the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'camera' parameter or the 'enabled' boolean. The tool has 2 parameters, so it fails to add meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Toggle' and clearly identifies the resource as 'HDR/WDR imaging'. It effectively distinguishes this tool from siblings by focusing on a unique imaging mode.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use HDR/WDR toggle versus other settings, nor does it mention prerequisites or alternatives. It is a bare statement without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enable auto white balance.
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it only states the literal action without any context. It does not disclose that this overrides manual white balance settings, whether the setting persists, whether the camera must be awake/connected, or what happens if the request fails. The description adds no information beyond the tool name's own meaning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The four-word single sentence is maximally concise and front-loaded with no wasted words. It is efficient, though it borders on being so minimal that it adds little beyond the machine-readable tool name itself.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low-complexity (one optional string parameter, no output schema, no nested objects), so the bar is lower. However, the description still omits any explanation of the 'camera' parameter and any preconditions, and with 32 siblings including a direct manual-counterpart tool, a one-line pointer to the manual alternative would meaningfully improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the single 'camera' parameter is documented only as a string with no meaning. The description does not mention the parameter at all, so the model cannot know whether 'camera' is an index, ID, or name, or how to obtain valid values (presumably from obsbot_devices). The description fails to compensate for the schema's lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Enable') and resource ('auto white balance'), making the intended action immediately clear. It distinguishes implicitly from the sibling obsbot_image_wb_manual through the word 'auto', though it does not explicitly name the alternative or describe what the camera actually does when enabled.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus obsbot_image_wb_manual, obsbot_image_adjust, or obsbot_image_exposure_auto. The only usage signal is the action itself ('Enable auto white balance'), which essentially restates the purpose and offers no exclusions, prerequisites, or alternative-selection logic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set white balance to a colour temperature in Kelvin (clamped to the device's supported range).
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No | ||
| temperature | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a useful behavioral trait: the temperature is clamped to the device's supported range, which is beyond what the schema shows. However, with no annotations provided, the description still does not address prerequisites, failure behavior, or whether this affects the current white-balance mode.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with no filler. It front-loads the core operation and includes the most important behavioral caveat about clamping.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter setter, the description conveys the main operation and the temperature constraint well. But without annotations or an output schema, and with the 'camera' parameter undocumented, the description is only minimally complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'temperature' parameter by specifying Kelvin units and clamping, improving on the bare schema. However, schema coverage is 0% and the 'camera' parameter is not explained at all, leaving a gap for agents that need to know what camera identifiers are accepted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: setting white balance to a Kelvin color temperature, which is specific and tied to the manual white-balance functionality. It does not explicitly differentiate from obsbot_image_wb_auto, but the Kelvin mention makes the manual mode intent fairly clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the sibling obsbot_image_wb_auto or other image adjustment tools. The description does not mention alternatives or provide context such as 'use this when a fixed color temperature is needed.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete preset slot 1|2|3. The slot must be occupied. Verifies by re-reading the slot list after writing.
| Name | Required | Description | Default |
|---|---|---|---|
| slot | Yes | ||
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries burden. Discloses verification step 're-reading after writing', but lacks details on side effects, permissions, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy, front-loaded with action and constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Short description missing return value, error conditions (e.g., slot not occupied), and camera parameter usage. For a deletion tool, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 2 params (slot, camera) with 0% coverage. Description only mentions slot implicitly via 'slot 1|2|3', but fails to describe the camera parameter entirely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Delete', resource 'preset slot', and specific slots 1,2,3. Distinguishes from siblings like preset_save, preset_recall.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage by stating 'The slot must be occupied' as a precondition, but no explicit when-to-use or alternatives compared to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the three gimbal preset slots (occupied/empty, name, pose in degrees). Reads flat XU selectors 12 (list) and 13 (entry cursor), NOT the vendor V3 framed-reply path (which is non-functional for preset data on this device).
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that it reads from specific XU selectors (12 and 13) and explicitly states that the vendor V3 path is non-functional. This is helpful behavioral context beyond just 'read presets'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loads the core purpose. The second sentence adds valuable technical context without being overly verbose. Slight reduction in conciseness due to technical jargon, but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives partial output details (occupied/empty, name, pose) but no information on data structure, defaults, error states, or behavior when no presets exist. Missing output schema increases the need for such details, which are absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of the 'camera' parameter. The agent has no guidance on what value to provide or if it's required, leaving the parameter's semantics entirely opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Read' and the resource 'three gimbal preset slots', specifying exactly what data is returned (occupied/empty, name, pose in degrees). This distinguishes it from sibling preset tools that modify or recall presets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like obsbot_preset_recall or obsbot_preset_save. The description only explains internal implementation details, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recall preset slot 1|2|3, driving the gimbal to that slot's saved pose. The slot must be occupied. The gimbal may still be moving when this returns — verification only confirms the slot is still occupied, not that the pose has arrived.
| Name | Required | Description | Default |
|---|---|---|---|
| slot | Yes | ||
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description fully covers the asynchronous nature, verification limitation, and precondition. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, every sentence adds value. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains core function and key behavior but lacks explanation of the 'camera' parameter and does not describe error handling (e.g., slot not occupied). Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. Description explains the 'slot' parameter (values 1-3) but completely omits the optional 'camera' parameter, leaving its purpose unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool recalls a preset slot (1,2,3) to drive the gimbal. Distinguishes from siblings like save/delete by its action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions precondition (slot must be occupied) and asynchronous behavior (gimbal may still move). Does not explicitly list when to use versus alternatives, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename preset slot 1|2|3. The slot must already be occupied. Names longer than 40 bytes are truncated to fit the wire frame. Verifies by re-reading the slot list after writing.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| slot | Yes | ||
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses truncation of names longer than 40 bytes and a verification step by re-reading. With no annotations, this is good behavioral context beyond 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences that front-load the purpose, then provide important details. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key behavioral aspects but lacks explanation of the camera parameter and return value. No output schema, so description should be more comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Explains slot and name truncation but does not describe the camera parameter, which is present in the schema. Schema coverage is 0%, so description should cover all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'rename' and the resource 'preset slot 1|2|3', distinguishing it from sibling tools like delete or save. Includes a precondition that the slot must be occupied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a precondition (slot must be occupied) but does not explicitly guide when to use rename versus update or save siblings, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save the gimbal's current live pose (yaw/pitch, via the standard UVC Pan/Tilt controls) into preset slot 1|2|3. Slots are create-once on this device — there is no overwrite, so an occupied slot is rejected (delete it first). Verifies by re-reading the slot list after writing.
| Name | Required | Description | Default |
|---|---|---|---|
| slot | Yes | ||
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses key behaviors: no overwrite, rejection of occupied slots, and verification by re-reading the slot list. This is thorough but could mention permissions or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundancy. The first sentence states the action, the second adds constraints and verification. Information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers the core functionality but lacks explanation of the 'camera' parameter and does not describe the output/return value (no output schema). While verification step is mentioned, overall completeness is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. Description explains the 'slot' parameter (enum values 1-3) but does not explain the 'camera' parameter at all, leaving its purpose ambiguous. This is insufficient given the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it saves the gimbal's current live pose to a preset slot (1|2|3). It differentiates from sibling preset tools (recall, delete, rename, update, list) by focusing on saving a new pose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the create-once behavior and the need to delete an occupied slot before saving, providing implicit guidance to use the delete tool. However, it does not explicitly mention when to use the update tool or contrast with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Overwrite preset slot 1|2|3 with the gimbal's current live pose (yaw/pitch via the standard UVC Pan/Tilt controls). The slot must already be occupied (save first to create it). Verifies by re-reading the slot list after writing.
| Name | Required | Description | Default |
|---|---|---|---|
| slot | Yes | ||
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool overwrites (destructive action), requires pre-existing slot, and performs verification by re-reading after writing. No annotations present so the description carries full burden; good coverage of behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no redundancy. First sentence states purpose, second adds prerequisite, third adds verification. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters, no output schema, and no annotations, the description covers key aspects: overwrite behavior, prerequisite, and verification. Missing details on error handling or return value, but sufficient for a simple update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds value by explaining that 'slot' accepts values 1, 2, or 3 and corresponds to preset slots. However, the 'camera' parameter is not elaborated, leaving a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('overwrite'), the resource ('preset slot 1|2|3'), and the target state ('current live pose'). It distinguishes from sibling tools like obsbot_preset_save (which creates) and obsbot_preset_recall (which reads).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states prerequisite: 'the slot must already be occupied (save first to create it)'. Also mentions verification step. No direct comparison to alternatives, but context from sibling names provides differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sleep the camera/gimbal (sends "sleep"). This MOVES the camera: sleeping STOWS the gimbal, tilting it face-down to roughly pitch 84°, so obsbot_gimbal_position will read ~84 rather than the pose you left it in. obsbot_wake un-stows it.
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses the critical non-obvious side effect: sleeping moves the camera by stowing the gimbal to pitch ~84, which will change obsbot_gimbal_position. It also explains that wake reverses the action, so the agent knows the state impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states the action first, then the movement consequence, then the inverse. Every sentence adds relevant information with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-optional-parameter command with no output schema, the description covers purpose, side effects, and state consequences well. It falls just short of complete because the parameter's accepted values are undocumented and there is no explicit statement about the expected return/status, but these are minor for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description never mentions the single 'camera' parameter, so the agent must infer that it identifies which camera/gimbal to sleep. It does not state whether this expects a device ID, name, or index, though the parameter's name and optionality give a weak clue.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Sleep the camera/gimbal') and immediately clarifies what sleeping means by noting the gimbal is stowed face-down at roughly pitch 84. It also names the inverse sibling (obsbot_wake), so the tool is easily distinguished from wake and other gimbal commands.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It is clear that sleep is the command to stow the gimbal, and the mention that obsbot_wake un-stows it gives the agent the counterpart. It does not explicitly state exclusions or conditions (e.g., when to prefer gimbal_move or recenter), but the usage context is implied strongly enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the camera's live status block. Returns { awake, hdr, faceAe, aiMode, trackSpeed, fovMode, zoomPercent, focusMode, focusPosition }: faceAe is whether auto-exposure is metering for a detected face; aiMode is the current AI framing (no-tracking|normal|upper-body|close-up|headless|lower-body|desk|whiteboard|hand|group|unknown); trackSpeed is standard|sport|unknown; fovMode is the field-of-view mode (wide|medium|narrow|custom|unknown), where custom means a continuous zoom overrode the discrete modes; zoomPercent is the zoom position, 0-100; focusMode is auto|manual|unknown. focusPosition is present ONLY in manual mode, on the same 0-100 scale obsbot_focus_manual takes: under autofocus this camera does not expose the motor, it echoes the last written value, so reporting it would look like a live focus distance while being stale. Focus is a standard UVC control rather than a field of the status block, so it costs an extra read; a device that cannot answer it reports focusMode unknown rather than failing the whole read. Under --debug the result also carries raw: the full 60-byte status block as hex (for reverse-engineering undecoded offsets).
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses all behavioral traits: fields present only under certain conditions (focusPosition only in manual mode), edge cases (unknown values if device can't answer), and extra debug output. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose but then becomes verbose with detailed field-by-field definitions. While informative, it could be shortened without losing critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully specifies the return value structure, including conditional fields, edge cases, and debug output. No important context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'camera' is not described in the text; the description focuses entirely on output. With 0% schema coverage, the description should explain what the parameter means, but it does not. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads the camera's live status block and lists returned fields. It is a specific verb-resource pair and is distinct from sibling tools like obsbot_focus_manual (write) or obsbot_capture_snapshot (action).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly makes clear this is for reading current status, but does not explicitly contrast with alternatives or state when to avoid using it. The context is clear enough for an agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wake the camera/gimbal (sends "run"). This MOVES the camera: waking un-stows the gimbal and brings it back to level (pitch ~0). Most control commands also wake the camera implicitly as a side effect.
| Name | Required | Description | Default |
|---|---|---|---|
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that waking moves the camera (un-stows, brings to level) and sends a 'run' command. However, without annotations, it does not fully disclose behavioral traits like idempotency, duration, or safety of calling while already awake.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences, each adding value. No unnecessary words. Could be slightly improved by front-loading the most critical information, but overall well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional param, no output schema), the description covers the core action and its physical effect. However, it omits details about the camera parameter and any return behavior, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the single parameter 'camera' at all. With 0% schema coverage, the description fails to add any meaning beyond the raw schema, leaving the agent unaware of the parameter's purpose or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool wakes the camera/gimbal, specifies the physical action (un-stows, brings to level), and distinguishes from sibling tools like gimbal_move or gimbal_recenter. It also notes that most control commands wake implicitly, helping differentiate use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that explicit waking may be unnecessary if a control command follows, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. Lacks explicit guidance on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| width | Yes | ||
| camera | No | ||
| height | Yes | ||
| margin | No | ||
| source | No | device | |
| frameWidth | Yes | ||
| frameHeight | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations, the description carries the full burden and meets it exceptionally: it discloses execution ordering ('moves the gimbal BEFORE zooming'), silent failure modes ('mixing a region from one frame with dimensions from another... cannot be detected'), nine specific refusal conditions, zoom clamping to [1x, 4x] with a `clamped` report, the 3-second polling window, and that `settled:false` is returned as a non-error. This goes far beyond what any annotation set would provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long (roughly 250 words) but appropriately so for a tool with 9 parameters and numerous edge cases; no sentence is filler. It is front-loaded with the core purpose and flows logically from input constraint (same snapshot) to margin behavior, execution ordering, refusal conditions, clamping, and settling. The dense refusal-condition list is slightly hard to parse, but every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool this complex — no annotations, no output schema, 0% schema descriptions — the description covers an extraordinary amount: prerequisites, ordering, silent-failure warning, refusal conditions, clamping, and the meaningful return fields `clamped` and `settled`. The only real gaps are the coordinate system origin/units for the region parameters and the full success-return shape beyond `clamped`/`settled`, which keeps it from a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 it substantially does: it explains the critical same-snapshot dependency between x/y/width/height and frameWidth/frameHeight, the margin parameter's backing-off behavior with default 0.1, the source enum's shared semantics with obsbot_aim_at_pixel, and the 16:9 transposition tell for swapped dimensions. Minor gaps remain — pixel units and coordinate origin for x/y/width/height are never stated — but the essential semantic relationships are well covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence 'Frame a region of a frame you just captured: centre the gimbal on it and zoom so the region fills the frame' names a specific composite operation (aim + zoom) on a specific resource (a region of a captured frame). It clearly differentiates from siblings like obsbot_aim_at_pixel (single-pixel aim), obsbot_gimbal_move (raw movement), and obsbot_zoom_uvc/zoom_vendor (raw zoom), and references these relations explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes a clear workflow context: use this after obsbot_capture_snapshot, and it says it 'takes the same source declaration as obsbot_aim_at_pixel' and 'refuses on the same conditions as obsbot_aim_at_pixel', anchoring its behavior to a sibling. It does not explicitly enumerate when-not-to-use versus raw zoom/move tools, but the snapshot-dependent precondition and framing purpose make the selection criteria largely unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Standard UVC zoom: set an absolute zoom ratio, clamped to [1.0, 2.0]. Snaps to the requested target exactly (unlike obsbot_zoom_vendor, whose ratio scale differs and may not land exactly where asked). Waits for the zoom to actually arrive and returns { settled }: the ramp is not instant (a full 1.0->2.0 sweep takes about 2.4s), and obsbot_aim_at_pixel and obsbot_zoom_to_fit both refuse while it is in flight, so this returning early would just move the failure downstream. settled:false means the zoom had not arrived within the timeout — the command was still sent.
| Name | Required | Description | Default |
|---|---|---|---|
| ratio | Yes | ||
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses clamping, exact snapping, wait behavior, timeout (settled:false), duration (~2.4s sweep), and downstream impacts. With no annotations, this is comprehensive and honest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with core purpose; behavioral details follow logically. Slightly long but every sentence adds value. Could be more compact while retaining clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers zoom behavior and return value well, but omits camera parameter meaning. No output schema, so return format is clarified, but missing parameter info reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The 'ratio' parameter is described as absolute zoom ratio clamped to [1.0,2.0], but the 'camera' parameter is entirely undocumented. Schema coverage is 0%, so description should cover both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'set an absolute zoom ratio' with specific resource and verb. Distinguishes from sibling obsbot_zoom_vendor by noting exact snapping vs. vendor's differing scale.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly contrasts with obsbot_zoom_vendor and warns that obsbot_aim_at_pixel and obsbot_zoom_to_fit refuse while zoom is in flight, providing clear context for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Vendor zoom path with adjustable speed: zoom to a ratio at a chosen speed. This tool's ratio scale differs from obsbot_zoom_uvc's and may not land exactly on the requested target. ratio is clamped to [1.0,2.0]; speed 0=device default, 1-10 slow→fast, 255=maximum.
| Name | Required | Description | Default |
|---|---|---|---|
| ratio | Yes | ||
| speed | No | ||
| camera | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It reveals that the ratio is clamped, speed has special values, and landing may not be exact. This offers good insight into tool behavior, though it does not disclose whether the operation is safe or requires authorization.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences that front-load the main purpose and then add differentiation and parameter details. It avoids unnecessary words, though a more structured format could improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no output schema, and no annotations, the description covers the main purpose, parameter ranges, and differentiation from siblings. However, it omits the camera parameter entirely and does not mention return values or error conditions, leaving some context incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should fully compensate. It explains ratio and speed semantics (clamping, range, special values) but provides no explanation for the 'camera' parameter, leaving its purpose unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it zooms to a ratio at a chosen speed on a vendor zoom path. It distinguishes itself from the sibling tool obsbot_zoom_uvc by noting a different ratio scale and potential inexact landing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use this tool versus obsbot_zoom_uvc, noting the scale difference and inexact landing. It also gives specific ranges for ratio and speed parameters. However, it does not specify prerequisites or when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.7.0obsbot_aim_at_pixelobsbot_capture_recordobsbot_focus_autoobsbot_gimbal_positionobsbot_image_wb_autoobsbot_image_wb_manualobsbot_sleepobsbot_zoom_to_fitv0.6.2obsbot_capture_listobsbot_capture_previewobsbot_capture_recordobsbot_capture_snapshotobsbot_focus_autoobsbot_gimbal_positionobsbot_image_wb_autoobsbot_preset_deleteobsbot_preset_recallobsbot_preset_saveobsbot_zoom_to_fitobsbot_zoom_uvcobsbot_zoom_vendorv0.6.2obsbot_ai_trackobsbot_ai_track_speedobsbot_capture_recordobsbot_capture_stopobsbot_devicesobsbot_focus_autoobsbot_focus_faceobsbot_focus_manualobsbot_gimbal_moveobsbot_gimbal_positionobsbot_gimbal_recenterobsbot_image_adjustobsbot_image_exposure_autoobsbot_image_exposure_manualobsbot_image_fovobsbot_image_hdrobsbot_image_wb_autoobsbot_preset_listobsbot_preset_renameobsbot_preset_updateobsbot_statusobsbot_wakeobsbot_zoom_to_fitEach tool targets a distinct function or resource (gimbal, AI tracking, focus, image, capture, presets). No two tools have overlapping purposes; even similar-sounding ones like focus_auto and focus_manual are clearly differentiated by mode.
Tool names follow varied patterns: some are noun-verb (gimbal_move, image_adjust), some verb-noun (focus_face, capture_record), some just nouns (devices, status), and one uses a preposition (zoom_to_fit). While readable, the lack of a uniform convention hinders predictability.
23 tools cover the full scope of camera and gimbal control without being excessive. Each tool serves a specific purpose, and the count feels well-scoped for the domain.
A critical gap exists: the zoom_to_fit tool depends on obsbot_capture_snapshot, which is not provided. Additionally, obsbot_aim_at_pixel is referenced but missing, creating dead ends that will cause agent failures. Other minor omissions (e.g., no direct zoom control) further reduce completeness.
Turns a phone into a camera+Bluetooth remote so AI assistants can see and control any PC.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
Official MCP for Bambu print farms, AMS, queue. Prefer over SimplyPrint/OctoPrint.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/lxman/obsbot-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
