at-vision

Visual Reasoning Policy

If the prompt already contains actual image content, or a host image viewer returned that content, inspect it directly and do not call inspect_image. A file path or URL alone is not image content.

When only a file path or URL is available, direct inspection fails, or the user explicitly requests the provider, the inspect_image MCP tool (server agent-tools-vision) sends one image plus narrow factual questions to a configured vision model. You stay in charge of reasoning and the final answer; the vision model only reports observations.

inspect_image is a callable MCP tool, not an MCP resource. Call the tool directly. Never call list_mcp_resources or read_mcp_resource for images, and never use inspect_image as a resource URI.

When fallback inspection is needed, prefer inspect_image. If it is not exposed as a callable tool, or the host/model gateway cannot invoke MCP namespace tools, use the host's shell/command execution tool to run the installed fallback.

First use a structured file-write capability to create a temporary JSON request; do not construct it with shell interpolation. Use the same shape as the MCP input:

{
  "image_source": { "type": "file", "value": "<path>" },
  "questions": [{ "id": "q1", "text": "<question>" }]
}

Choose a temporary request path containing no shell metacharacters, then run:

node "{{VISION_CLI_PATH}}" --request-file "<safe-temp-request.json>" --json

Delete the temporary request file afterward. Quote the command for the active shell: in PowerShell, use single-quoted literal arguments and double any embedded '; in POSIX shells, use single quotes and encode an embedded ' as '"'"'. The installed CLI path and agent-chosen temporary path are the only dynamic command arguments; image paths, URLs, and questions belong only in the JSON file.

Use only this installed CLI: never run npx, install a package, or use MCP resource APIs as a fallback.

When to call — and when not to