Skip to main content
Glama
Ubadream

AGY Visual Witness MCP

by Ubadream
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

AGY Visual Witness MCP

A provider-specific visual reader for text-only agents. It uses Google's Antigravity (agy) CLI and returns structured visual evidence, not an acceptance verdict.

Three operations are intentionally separate:

  • WHOLE_READ: scene-level structured description through pinned ModLens.

  • TARGETED_WITNESS: one image plus one visible-evidence question.

  • COMPARE_PREFILTER: two images plus a list of visible difference candidates.

Every response declares:

control_surface = QA_ONLY
epistemic_label = INFERRED
authority = evidence_only_no_gate_no_acceptance_no_promotion
reproducibility_class = NOT_REPRODUCIBLE

It must not replace deterministic size/binding/AOV checks, pixel diffs, histograms, IoU measurements, human identity/art-direction judgment, or final promotion authority.

Relationship to ModLens

WHOLE_READ invokes @liustack/modlens as an external CLI. The targeted and comparison operations are separate clean-room adapters that invoke agy structured output directly. No ModLens source is vendored here.

Related MCP server: Vision MCP Server

Install

  1. Install and sign in to the official agy CLI.

  2. Install Node.js/npm if you want WHOLE_READ.

  3. Install this package:

pipx install .
# or
uv tool install .

CLI

agy-visual doctor

agy-visual read --root /path/to/images --image /path/to/images/scene.png \
  --operation WHOLE_READ

agy-visual read --root /path/to/images --image /path/to/images/hand.png \
  --operation TARGETED_WITNESS \
  --prompt "How many fingers are visibly countable? Mark occluded digits unknown."

agy-visual read --root /path/to/images \
  --image /path/to/images/before.png --image /path/to/images/after.png \
  --operation COMPARE_PREFILTER --prompt "List visible geometry differences only."

Use --dry-run to validate paths, hashes, operation contract, and runtime identity without sending an image to a provider.

MCP

Codex config.toml example:

[mcp_servers.agy-visual-witness]
command = "agy-visual-witness-mcp"
env = { AGY_VISUAL_ROOTS = "/absolute/allowed/image/root" }

Tools:

  • describe_image_gemini

  • agy_visual_doctor

Boundaries

  • Local files only; URLs are rejected.

  • Images must stay under AGY_VISUAL_ROOTS or the roots passed by the caller.

  • Supported formats: PNG, JPEG, WebP, GIF, BMP; maximum 25 MiB each.

  • Provider execution receives staged copies in an otherwise empty temporary directory. Image text is treated as untrusted data, never as instructions.

  • Input evidence includes SHA-256 and byte size.

  • TARGETED_WITNESS requires exactly one image and a non-empty question.

  • COMPARE_PREFILTER requires exactly two images.

Runtime identity for comparison

Multi-image behavior has changed across agy releases. Comparison therefore fails closed unless the binary identity is known:

  • Windows agy 1.1.9 is recognized by its tested SHA-256.

  • Other builds can be pinned with AGY_VISUAL_EXPECTED_SHA256 after independent verification.

  • AGY_VISUAL_ALLOW_UNVERIFIED_COMPARE=1 is an explicit escape hatch. The output still reports OBSERVED_NOT_PINNED; do not treat it as reproducible.

Version probes run with AGY auto-update disabled and the executable is hashed again after the probe. If a configured/known hash does not match, or the binary changes during probing, every provider operation is blocked before egress. The unverified-compare escape hatch never overrides an explicit identity mismatch.

AGY_BIN selects an explicit executable. AGY_VISUAL_MODEL overrides the default gemini-3.6-flash-low. Provider model availability and quota can change.

Security

Do not attach secret-bearing screenshots unless the selected external provider is authorized to receive them. Never promote model output to a deterministic gate merely because the call returned successfully.

See SECURITY.md.

Observed pre-release checks and their evidence limits are recorded in docs/VALIDATION.md.

License

MIT. This project is independent and is not endorsed by Google, ModLens, or OpenAI. ModLens remains under its own MIT license and is used only through its documented CLI interface.

Available Tools

2 tools
agy_visual_doctorC

Report agy/npx runtime presence and non-secret identity evidence.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are present, so the description carries the full burden of disclosing behavior. It mentions 'non-secret' to indicate that secrets are not exposed, but it does not explain side effects, execution context, dependencies, or what evidence is returned, leaving significant behavioral ambiguity.

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

Conciseness5/5

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

The description is a single, concise sentence that leads with the verb 'Report' and packs the core purpose without unnecessary words. It is appropriately sized for a zero-parameter tool.

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

Completeness2/5

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

With no annotations and no output schema, the description needs to explain what the tool returns or how it behaves. It only says 'evidence' is reported, but not the format, structure, or examples of that evidence, leaving the context incomplete for an AI agent.

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

Parameters4/5

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

The tool has zero parameters and the schema description coverage is 100%, so no parameter explanation is needed. The baseline score of 4 applies because there are no parameters to document.

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

Purpose3/5

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

The description uses the verb 'Report' and names the subject 'agy/npx runtime presence and non-secret identity evidence', which gives a general sense of a diagnostic check. However, the phrase 'non-secret identity evidence' is vague and does not clearly define the exact resource or outcome, making the purpose only partially clear.

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

Usage Guidelines2/5

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 tool describe_image_gemini. The description only states what it does, not under what circumstances it should be chosen or excluded.

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

describe_image_geminiB

Return QA-only visual evidence; never a deterministic acceptance verdict.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNo
rootsNo
imagesYes
promptNo
dry_runNo
operationNoWHOLE_READ
timeout_msNo

TDQS

B3/5.0
Behavior2/5

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

With no annotations, the description must fully disclose behavior, but it only adds one non-deterministic output trait. It does not mention read-only nature, external API calls, permissions, rate limits, or output format. The 'never a deterministic acceptance verdict' is useful but minimal.

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

Conciseness5/5

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

The description is one focused sentence, front-loaded with the core purpose and a key limitation. Every word earns its place; no fluff or repetition.

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

Completeness1/5

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

For a tool with 7 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain what 'visual evidence' looks like, how parameters influence behavior, or any operational details. Clearly inadequate for safe and correct invocation.

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

Parameters1/5

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 for any of the 7 parameters (images, model, roots, prompt, dry_run, operation, timeout_ms). The description completely fails to compensate for the lack of param documentation.

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

Purpose4/5

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

The description clearly states the tool returns QA-only visual evidence and explicitly denies deterministic acceptance verdicts, giving a specific verb and resource. However, it does not explicitly differentiate from sibling tool agy_visual_doctor, though the QA-only scope helps distinguish it from a verification tool.

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

Usage Guidelines4/5

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

The description provides clear usage context: use for QA visual evidence, and a when-not: never for deterministic acceptance. It implies alternatives for acceptance checks but does not name any tool directly. This is clear context without explicit alternative listing.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedagy_visual_doctor
    • First observeddescribe_image_gemini
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one analyzes images via Gemini, the other checks runtime presence and identity evidence. There is no overlap or ambiguity between them.

Naming Consistency2/5

The naming conventions are inconsistent: 'describe_image_gemini' follows a verb_noun_model pattern, while 'agy_visual_doctor' uses a product-prefixed noun phrase with no verb. This makes the set feel disjointed.

Tool Count4/5

With only two tools, the server is minimal but still coherent with its stated 'Visual Witness' purpose. It feels slightly thin but not unreasonable for a specialized utility.

Completeness3/5

The tools cover image description and runtime diagnostics, but the 'Visual Witness' domain might benefit from additional operations like image comparison or evidence storage. There is no obvious dead end, but the surface is narrow.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers