Bug

take_screenshot is advertised and prompted as part of Studio's local-site workflow, but it does not accept the local-site addressing shape used by the rest of the local-site MCP tool surface.

Most local-site tools accept nameOrPath, resolve it through Studio's site config, then operate on the resolved site. take_screenshot only accepts url, so an agent operating on an active local site can naturally call it with nameOrPath + path and get rejected by MCP schema validation before the handler runs.

Evidence

Runtime tool schema probe against studioToolDefinitions showed:

{
  "wp_cli": ["nameOrPath", "command"],
  "validate_blocks": ["nameOrPath", "filePath", "content"],
  "take_screenshot": ["url", "viewport"]
}

Focused temporary Vitest probe passed while confirming this contrast:

npm -w wp-studio exec vitest run ai/tests/screenshot-contract.temp.test.ts

Relevant code locations on current trunk/BFB worktrees:

• Local prompt tells agents to screenshot the local site after build: apps/cli/ai/system-prompt.ts
• Local-site resolver pattern: apps/cli/ai/tools.ts → resolveSite( nameOrPath )
• wp_cli schema uses nameOrPath
• validate_blocks schema uses nameOrPath
• take_screenshot schema requires url only

Live benchmark artifact captured the real failure:

{
  "name": "take_screenshot",
  "input": {
    "nameOrPath": "/tmp/studio-bfb-bench-single-1777579294/studio-agent-site-build-artifacts/sites/bfb-38088-1777579299409-zrmah4u33v9",
    "path": "/"
  }
}

MCP rejected it before the handler ran:

MCP error -32602: Input validation error: Invalid arguments for tool take_screenshot:
[
  {
    "expected": "string",
    "code": "invalid_type",
    "path": ["url"],
    "message": "Invalid input: expected string, received undefined"
  }
]

The same run later retried with an absolute URL:

{
  "name": "take_screenshot",
  "input": {
    "url": "http://localhost:9092/"
  }
}

That indicates the failure is not a browser/screenshot runtime failure. It is the argument contract mismatch.

Why this is a Studio bug

The local-site MCP tool surface trains the agent to identify sites by nameOrPath:

• site_info
• site_start
• site_stop
• site_delete
• preview_create
• preview_list
• preview_update
• wp_cli
• validate_blocks
• need_for_speed
• rank_me_up
• site_push
• site_pull
• site_import
• site_export

take_screenshot is the exception even though the local prompt tells the agent to use it as part of the same local-site build loop.

Expected behavior

take_screenshot should accept either:

• url for the existing absolute-URL behavior, or
• nameOrPath plus optional path for local Studio sites.

When url is absent and nameOrPath is present, Studio should:

1. Resolve the site with the existing resolveSite( nameOrPath ) helper.
2. Build the base URL with getSiteUrl( site ).
3. Normalize and append path when provided, defaulting to /.
4. Capture the screenshot of that resolved URL.

Suggested test coverage

Add focused tests in apps/cli/ai/tests/tools.test.ts:

• URL-only screenshot path remains supported.
• nameOrPath resolves a local site URL.
• nameOrPath + path resolves a site-relative URL.
• Missing both url and nameOrPath returns a clear validation/tool error.

Scope

This should be a small Studio MCP tool contract fix. It does not require BFB, benchmark harness changes, or screenshot runtime changes.