# Tools Guide

This is the human-oriented overview for how to use the tool surface. The full, generated catalog of exposed tools (with schemas) is in `docs/tools.md`.

## How to use tools

- Prefer **curated tools** first. They include search and summary flows for common VRChat tasks.
- Auto-generated API-gap coverage is exposed through `vrchat_read`, `vrchat_write`, and `vrchat_delete`. Pass an OpenAPI `operationId`; use `vrchat_operations` to list available operation IDs and `vrchat_operation_details` for exact params/body schemas. Generated routers omit hard-skipped operations and operations already covered by curated tools. Use `generatedReadTools.operationIds` or `generatedWriteTools.operationIds` only when you want to narrow the remaining generated surface.
- Curated write tools are enabled by default for local full-capability use. Set `writes.allow = false` (or `VRCHAT_MCP_ALLOW_WRITES=false`) for read-only mode.
- The MCP client or agent harness is expected to control approval/denial for account-changing tool calls.
- Group write actions are restricted by `groups.allowlist` when set.
- Account-gallery image uploads require an absolute path inside `uploads.allowedRoots`. Empty roots disable local upload intake. Group authorization is enforced by the post or event tool that later attaches the returned file ID.
- Do not expose this server as a hosted/public MCP service with VRChat cookies. Keep it local and user-controlled.

## Metadata budget

Tool names, tool descriptions, argument names, argument descriptions, and schema structure consume model context. Run `npm run metrics:tool-budget` to report the estimated default tool metadata token budget, category breakdown, initial tool-list cost, full schema cost, repeated argument-description hotspots, blank tool-description coverage, argument-description coverage, and the largest tools by metadata size. CI includes this in `npm run metrics`; keep the budget from drifting upward unless the extra guidance is worth the context cost.

## MCP resources

- `vrchat://friends/changes{?after,limit}` - delta feed for friend updates.
- `vrchat://friends/snapshot{?includeOffline,pageSize,maxPages}` - friends snapshot.

## Swagger UI (mcpo)

- Run `npm run mcpo` to spin up an OpenAPI proxy with Swagger UI.
- This development proxy is separate from the native MCP Streamable HTTP transport (`--transport http`).
- `npm run mcpo` requires `uvx` (from Astral’s `uv`) to be installed.
- Open `http://localhost:8000/docs` to browse and try tool calls.
- For config-based setup (Claude Desktop config + hot reload), see `README.md`.

## Where the truth lives

- `docs/tools.md` is generated from code + the OpenAPI spec and includes curated tools plus the generated catalog.
- `docs/curated-tools.md` describes the curated tool charter and risk tiers.