Integrates with Perforce P4 version control system, providing tools for managing changelists, files, shelves, workspaces, jobs, reviews, streams, and server information.
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., "@Perforce P4 MCP Server list my pending changelists"
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.
Comprehensive P4 integration: Read/write tools across files, changelists, shelves, workspaces, jobs, reviews, streams, and server information.
Code review workflows: P4 Code Review support for review discovery, voting, state transitions, commenting, and participant management.
Safety first: Read-only mode by default, ownership checks, interactive MCP elicitation (PROCEED/CANCEL) for destructive delete and obliterate operations.
Flexible toolsets: Configure which tool categories to enable: server, files, changelists, shelves, workspaces, jobs, reviews, and streams.
Robust logging: Application and session logging to the logs/ directory.
Optional telemetry: Consent-gated usage statistics. Disabled by default.
Cross platform: Supported on macOS, Linux and Windows with pre-built binaries.
Related MCP server: Conduit
P4 Server access: Connection to a P4 Server with proper credentials
Authentication: Valid P4 login (ticket-based or password)
Component | Supported Versions |
Operating Systems | Windows 10+macOS 12+Linux (glibc 2.34+, e.g. Ubuntu 22.04+, Rocky Linux 9+) |
Perforce P4 Server | 2026.1 (earlier versions untested) |
Python | 3.11+ (required only for building from source) |
If you have uv installed, you can run P4 MCP Server directly without any manual installation:
# Run the server
uvx p4mcp-server
# Check version
uvx p4mcp-server --version
# Run with arguments
uvx p4mcp-server --readonly --allow-usageThis automatically fetches and runs the latest version from PyPI. No Python virtual environment setup or dependency management needed.
Requirements:
uv installed on your system
Python 3.11+ (uv will handle this automatically)
Download the appropriate binary for your operating system:
macOS: p4-mcp-server-mac.zip
Windows: p4-mcp-server-win.zip
Linux: p4-mcp-server-linux.zip
Extract and use the executable directly. No Python installation is required.
# macOS / Linux
unzip p4-mcp-server-mac.zip # or p4-mcp-server-linux.zip
./p4-mcp-server --help# Windows
Expand-Archive p4-mcp-server-win.zip -DestinationPath .
.\p4-mcp-server.exe --helpRequirements:
Python 3.11+ (with Tkinter)
Build:
macOS: chmod +x build.sh && ./build.sh package
Linux: chmod +x build.sh && ./build.sh package
Windows: build.bat package
Output:
macOS & Linux: p4-mcp-server-<version>.tgz
Windows: p4-mcp-server-<version>.zip
Run the P4 MCP Server directly on your machine using the default STDIO transport.
Add the following to your mcp.json:
{
"mcpServers": {
"perforce-p4-mcp": {
"command": "/absolute/path/to/p4-mcp-server",
"env": {
"P4PORT": "ssl:perforce.example.com:1666",
"P4USER": "your_username",
"P4CLIENT": "your_workspace"
},
"args": [
"--readonly", "--allow-usage"
]
}
}
}Note: This example shows explicit
envvalues. IfP4CONFIGis set, you can omit them and use the generic configuration example in theMCP client configurationsection instead.
Run the P4 MCP Server from a Docker container with STDIO transport, allowing MCP clients to manage the container lifecycle.
Note: Docker-based execution is currently supported on macOS and Linux only.
Prerequisites
Docker installed and running
Valid P4 credentials and access to a P4 server
Pull the Docker image
docker pull ghcr.io/perforce/p4mcp-server:latestcd /path/to/p4mcp-server
docker build -t ghcr.io/perforce/p4mcp-server .Configure MCP Client
Add the following to your mcp.json:
{
"servers": {
"perforce-p4mcp-docker": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"--hostname", "your-hostname",
"-e", "P4PORT=ssl:perforce.example.com:1666",
"-e", "P4USER=your_username",
"-e", "P4CLIENT=your_workspace",
"-v", "/Users/your_username/.p4tickets:/home/mcpuser/.p4tickets:ro",
"ghcr.io/perforce/p4mcp-server:latest"
]
}
}
}Configuration Options
Flag | Description |
| Interactive mode (required for STDIO) |
| Remove container when stopped |
| Match workspace host restriction |
| P4 server address |
| P4 username |
| Workspace name |
| Mount P4 tickets file |
Authentication
Using P4 tickets:
# macOS/Linux
-v /Users/your_username/.p4tickets:/home/mcpuser/.p4tickets:roNote: Use the full path to your tickets file (not
~). After runningp4 login, restart the MCP server to pick up the new ticket.
Using a password:
-e P4PASSWD="your_password"Workspace Host Restrictions
⚠️ Important: Docker containers have their own hostname, which differs from your local machine. If your P4 workspace is restricted to a specific host, operations like
syncwill fail.
To resolve this, set the container hostname to match your workspace's host restriction:
--hostname your-hostnameTo find your workspace host name:
# macOS/Linux
p4 client -o your_workspace | grep "^Host:"Mounting Client Root for Write Operations
⚠️ Important: By default, the Docker container cannot access your local workspace files. For write operations like
sync,submit, orreconcile, you must mount your client root directory into the container at the same path.
Add a volume mount for your client root:
-v /path/to/your/client/root:/path/to/your/client/rootExample configuration with client root mounted:
{
"servers": {
"perforce-p4mcp-docker": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"--hostname", "your-hostname",
"-e", "P4PORT=ssl:perforce.example.com:1666",
"-e", "P4USER=your_username",
"-e", "P4CLIENT=your_workspace",
"-v", "/Users/your_username/.p4tickets:/home/mcpuser/.p4tickets",
"-v", "/path/to/client/root:/path/to/client/root",
"ghcr.io/perforce/p4mcp-server:latest"
]
}
}
}To find your client root:
p4 client -o your_workspace | grep "^Root:"Note: The mount path inside the container must match the client root path exactly, as P4 tracks files by their absolute paths.
Run the MCP server on a VM using the HTTP transport, allowing clients to connect over the network.
Start the server on the VM:
P4PORT=ssl:perforce.example.com:1666 P4USER=your_username P4PASSWD=YOUR_TICKET ./p4-mcp-server --readonly --transport http --port 8000Configure the MCP client:
Add the following to your mcp.json:
{
"servers": {
"perforce-p4-mcp": {
"type": "http",
"url": "http://<ip-or-hostname>:8000/mcp"
}
}
}Note: Ensure the VM's firewall allows inbound connections on the chosen port. For production use, consider placing the server behind a reverse proxy with TLS.
Run the MCP server in a Docker container using HTTP transport and expose the MCP endpoint over a host port.
Start the container:
docker run --rm -p 8000:8000 \
-e P4PORT=ssl:perforce.example.com:1666 \
-e P4USER=your_username \
-e P4PASSWD=YOUR_TICKET \
ghcr.io/perforce/p4mcp-server:latest \
python3 -m p4mcp.main --readonly --transport http --port 8000Configure the MCP client:
Add the following to your mcp.json:
{
"servers": {
"perforce-p4-mcp": {
"type": "http",
"url": "http://<ip-or-hostname>:8000/mcp"
}
}
}Note: Docker supports HTTP-based deployment as well. The container image defaults to STDIO transport, so the HTTP startup command must explicitly override the default command. If you need write operations, also mount the client root and ticket file paths into the container.
Note: In all configuration examples below, if
P4CONFIGis set, you do not need to set any environment variables in theenvblock. The server will use the configuration from the specified P4CONFIG file instead.
Tip: If you have uv installed, you can use
uvx p4mcp-serverinstead of/absolute/path/to/p4-mcp-serverin thecommandfield. This eliminates the need to download or build binaries manually.{ "mcpServers": { "perforce-p4-mcp": { "command": "uvx", "args": [ "p4mcp-server", "--readonly", "--allow-usage" ], "env": { "P4PORT": "ssl:perforce.example.com:1666", "P4USER": "your_username", "P4CLIENT": "your_workspace" } } } }{ "mcpServers": { "perforce-p4-mcp": { "command": "/absolute/path/to/p4-mcp-server", "env": { }, "args": [ "--readonly", "--allow-usage" ] } } }
See the JetBrains AI Assistant VCS Integration documentation for detailed configuration steps.
See the Claude Code MCP docs for more information.
Using uvx (no installation required):
{
"mcpServers": {
"perforce-p4-mcp": {
"command": "uvx",
"args": [
"p4mcp-server",
"--readonly", "--allow-usage"
],
"env": {
"P4PORT": "ssl:perforce.example.com:1666",
"P4USER": "your_username",
"P4CLIENT": "your_workspace"
}
}
}
}Using pre-built binary:
{
"mcpServers": {
"perforce-p4-mcp": {
"command": "/absolute/path/to/p4-mcp-server",
"env": {
"P4PORT": "ssl:perforce.example.com:1666",
"P4USER": "your_username",
"P4CLIENT": "your_workspace"
},
"args": [
"--readonly", "--allow-usage"
]
}
}
}See the Cursor MCP documentation for more information.
{
"mcpServers": {
"perforce-p4-mcp": {
"command": "/absolute/path/to/p4-mcp-server",
"env": {
"P4PORT": "ssl:perforce.example.com:1666",
"P4USER": "your_username",
"P4CLIENT": "your_workspace"
},
"args": [
"--readonly", "--allow-usage"
]
}
}
}See the Eclipse MCP documentation for more information.
{
"servers": {
"perforce-p4-mcp": {
"command": "/absolute/path/to/p4-mcp-server",
"env": {
"P4PORT": "ssl:perforce.example.com:1666",
"P4USER": "your_username",
"P4CLIENT": "your_workspace"
},
"args": [
"--readonly", "--allow-usage"
]
}
}
}See the Kiro MCP documentation for more information.
{
"mcpServers": {
"perforce-p4-mcp": {
"command": "/absolute/path/to/p4-mcp-server",
"env": {
"P4PORT": "ssl:perforce.example.com:1666",
"P4USER": "your_username",
"P4CLIENT": "your_workspace"
},
"args": [
"--readonly", "--allow-usage"
]
}
}
}See the VS Code documentation for more information.
{
"servers": {
"perforce-p4-mcp": {
"command": "/absolute/path/to/p4-mcp-server",
"env": {
"P4PORT": "ssl:perforce.example.com:1666",
"P4USER": "your_username",
"P4CLIENT": "your_workspace"
},
"args": [
"--readonly", "--allow-usage"
]
}
}
}See the Windsurf MCP documentation for more information.
{
"mcpServers": {
"perforce-p4-mcp": {
"command": "/absolute/path/to/p4-mcp-server",
"env": {
"P4PORT": "ssl:perforce.example.com:1666",
"P4USER": "your_username",
"P4CLIENT": "your_workspace"
},
"args": [
"--readonly", "--allow-usage"
]
}
}
}P4PORT - P4 Server address. Examples: ssl:perforce.example.com:1666, localhost:1666
P4USER - Your P4 username
P4CLIENT - Your current P4 workspace. Optional, but recommended
P4MCP_MAX_RESULTS - Cap on the number of rows the P4 server returns per command (p4.maxresults). Default: 10000. Set to 0 to disable the limit (server default in effect). When a command would exceed this limit the server aborts it with an error rather than truncating results, so keep the value generous. Can be overridden by the --max-results CLI argument. Must be a non-negative integer; an invalid value fails fast at startup before any P4 connection is attempted.
P4MCP_MAX_SCAN_ROWS - Cap on the number of rows the P4 server scans per command (p4.maxscanrows). Unset by default, so admin/group policy governs scan limits. Can be overridden by the --max-scan-rows CLI argument. Must be a non-negative integer when supplied.
P4MCP_LOG_DIR - Directory for log files. Default: logs/ in the server executable's directory. Can be overridden by the --log-dir CLI argument.
P4MCP_TLS_CA_MODE - TLS certificate source mode.
system (default): use OS trust store via truststore. Note: In this mode, truststore overrides the verify= parameter — custom CA bundles set via P4MCP_CA_BUNDLE or --ca-bundle are ignored. To use a custom CA bundle, set P4MCP_TLS_CA_MODE=certifi.
certifi: disable truststore injection and use default Python TLS certificate behavior. Custom CA bundles (P4MCP_CA_BUNDLE / --ca-bundle) take effect only in this mode.
P4MCP_SSL_VERIFY - Set to false to disable SSL verification for P4 Code Review API requests. Default: true. Works in both TLS modes.
P4MCP_CA_BUNDLE - Path to a custom CA certificate bundle (PEM) for P4 Code Review API requests. Takes priority over P4MCP_SSL_VERIFY. Requires P4MCP_TLS_CA_MODE=certifi to take effect.
OTEL_EXPORTER_OTLP_ENDPOINT - OTLP collector endpoint for telemetry export. Default: https://grpc.public.prd.shared.perforce.com.
OTEL_EXPORTER_OTLP_PROTOCOL - OTLP export protocol. Only grpc is supported; other values fall back to grpc with a warning.
--readonly - Control write operations.
If present, uses read-only mode. Safe for exploration and testing.
If missing, enables write operations. Requires proper permissions on your P4 Server.
--allow-usage - Allow usage statistics.
If present, allows anonymous usage statistics collection.
If missing, disables all usage statistics.
--toolsets - Specify which tool categories to enable.
Available: files, changelists, shelves, workspaces, jobs, reviews, streams
Default: All toolsets enabled.
query_server is always available regardless of the --toolsets setting.
--search-transform - Enable search-based tool discovery to reduce token overhead.
regex — Expose a regex pattern-matching search tool. Best for targeted lookups.
bm25 — Expose a natural-language relevance-ranked search tool. Best for exploratory queries.
both — Expose both search tools with distinct names (regex_search_tools/regex_call_tool and semantic_search_tools/semantic_call_tool).
If omitted, the full tool catalog is sent to the client (default, backward-compatible).
When enabled, query_server is always directly visible to the client.
Security: Admin permission checks (CheckPermissionMiddleware) and --readonly filtering remain fully enforced. Search transforms query the real tool catalog internally, so tools blocked by middleware or excluded by read-only mode are never discoverable or callable through the search interface.
--max-results <N> - Cap on the number of rows the P4 server returns per command (p4.maxresults).
Default: 10000. Set to 0 to disable the limit (server default in effect).
Protects against runaway AI-driven queries exhausting local memory or overwhelming the server.
When a command would exceed this limit the server aborts it with an error — it does not truncate — so keep the value generous.
Must be a non-negative integer; an invalid value fails fast at startup before any P4 connection is attempted.
Priority order:
--max-results>P4MCP_MAX_RESULTS> default (10000).
--max-scan-rows <N> - Cap on the number of rows the P4 server scans per command (p4.maxscanrows).
Unset by default, so admin/group policy governs scan limits.
Must be a non-negative integer when supplied; an invalid value fails fast at startup.
Priority order:
--max-scan-rows>P4MCP_MAX_SCAN_ROWS> default (unset).
--ssl-no-verify - Disable SSL certificate verification for P4 Code Review API requests.
Useful for environments with self-signed or internal CA certificates.
Works in both system and certifi TLS modes.
These SSL options only affect HTTPS Swarm connections. If the Swarm URL is http://, they have no effect.
--ca-bundle <path> - Path to a custom CA certificate bundle (PEM) for P4 Code Review API requests.
Use this to trust an internal CA without disabling verification entirely.
Requires P4MCP_TLS_CA_MODE=certifi to take effect. In the default system mode, truststore uses the OS trust store and ignores this setting.
If both --ca-bundle and --ssl-no-verify are provided, --ca-bundle takes priority (verification is performed using the specified bundle).
Priority order:
--ca-bundle>--ssl-no-verify>P4MCP_CA_BUNDLE>P4MCP_SSL_VERIFY> default (true). CLI args take priority over environment variables.
--log-dir <path> - Directory for log files.
Specify a custom directory for log files (both application and session logs).
Default: logs/ in the server executable's directory.
Can also be set via P4MCP_LOG_DIR environment variable.
CLI argument takes priority over environment variable.
Priority order:
--log-dir>P4MCP_LOG_DIR> default (logs/in the server executable's directory).
Use absolute paths for the command field in all configurations.
Ensure environment variables are properly set for each host.
Different hosts may have different argument parsing. Refer to the host's documentation.
Example setup
# Windows (PowerShell)
$env:P4PORT = "ssl:perforce.example.com:1666"
$env:P4USER = "your_username"
$env:P4CLIENT = "your_workspace"# macOS/Linux (Bash)
export P4PORT="ssl:perforce.example.com:1666"
export P4USER="your_username"
export P4CLIENT="your_workspace"
P4USERmust be a standard user. P4 MCP Server runs commands such asp4 describeandp4 changesthat aservice-type user is not permitted to run, so a service user will cause tools to fail at runtime. ConfigureP4USERwith a Perforce user of typestandard. Seep4 userin the P4 CLI documentation.
These options bound how much work a single P4 command can do, protecting the server against runaway queries:
max_results — Caps how many rows the P4 server returns per command. On by default with a generous value to protect against runaway queries. Lower the value to tighten the bound. Configured via P4MCP_MAX_RESULTS or --max-results.
max_scan_rows — Caps how many rows the server scans per command. Unset by default (governed by admin/group policy). Configured via P4MCP_MAX_SCAN_ROWS or --max-scan-rows.
Manage access through group-level and user-level server properties. P4 resolves each property to a single value using two rules, applied in order:
Highest sequence number wins. The -s flag is the primary sort key. It applies across all scopes — a group property at -s5 beats a user property at -s1 or default.
At the same sequence number, scope is the tiebreaker: user > group > global. Between groups at the same sequence, the alphabetically-first group name wins.
P4 does not compare values semantically. It does not know that false is more restrictive than true. The winning property's value is returned as-is and checked by the MCP server.
If no property applies, MCP remains enabled unless explicitly disabled.
To disable MCP for all users:
p4 property -a -n mcp.enabled -v falseTo re-enable group/user-based control, delete the global property first:
p4 property -d -n mcp.enabledTo prevent access for all members of a specific group:
p4 property -a -n mcp.enabled -v false -g noaccessgroupYou can set multiple group restrictions the same way.
When a user belongs to multiple groups with conflicting settings, P4's property resolution determines which value wins.
The highest sequence number (-s) wins. At equal sequence numbers, the alphabetically-first group name wins.
Example:
p4 property -a -n mcp.enabled -v false -s1 -g noaccessgroup
p4 property -a -n mcp.enabled -v true -s2 -g accessgroupIn this example, accessgroup wins because -s2 is higher than -s1.
To block a specific user regardless of group membership:
p4 property -a -n mcp.enabled -v false -u noaccessuserAt the same sequence number, user-level properties override group-level and global settings (P4's scope tiebreaker).
Example: Even if noaccessuser is in accessgroup (where MCP is enabled), the user property at the same sequence takes precedence and MCP is disabled.
Note: A group property at a higher
-svalue can override a user property at a lower sequence number. To ensure a user-level property always wins, give it a high-svalue or ensure no group properties use a higher sequence.
Restrict which toolsets are available server-wide using mcp.toolsets.allowed. Only listed toolsets will be enabled; all others are blocked.
Available toolsets: server, changelists, files, jobs, reviews, shelves, workspaces, streams
Allow only changelists and files:
p4 property -a -n mcp.toolsets.allowed -v changelists,filesRemove the allowlist to restore all toolsets:
p4 property -d -n mcp.toolsets.allowedDisable all write operations (modify tools) while keeping read operations (query tools) available:
p4 property -a -n mcp.toolsets.write -v falseRe-enable writes:
p4 property -a -n mcp.toolsets.write -v trueWhen write=false, all modify_* tools are blocked but all query_* tools continue to work.
Enable or disable individual toolsets for a specific group.
Disable a toolset for a specific group:
p4 property -a -n mcp.toolset.changelists.enabled -v false -g reviewersUsers in reviewers are blocked from changelists. Users in other groups (with no explicit setting) retain default access.
To restrict a toolset to only one group, disable it for every other group that should not have access:
p4 property -a -n mcp.toolset.files.enabled -v false -g reviewers
p4 property -a -n mcp.toolset.files.enabled -v false -g interns
# Only groups without an explicit "false" retain default access to filesNote: All toolsets are enabled by default. Setting
enabled=truefor a group is redundant unless you are explicitly overriding a previousfalsesetting. At the same sequence number, a group property overrides a global property (P4's scope tiebreaker), so a groupenabled=truecan override a globalenabled=false. To ensure a global setting cannot be overridden, give it a high-svalue. To isolate a toolset to specific groups, disable it for the groups you want to block.
Control write access for each toolset at the group level.
Disable writes for a specific toolset per group:
p4 property -a -n mcp.toolset.workspaces.write -v false -g reviewersThis blocks modify_workspaces for the group while query_workspaces remains accessible.
Restrict a group to specific tools within a toolset using mcp.toolset.<name>.tools.
Allow only query_files (block modify_files) for developers:
p4 property -a -n mcp.toolset.files.tools -v query_files -g developersAllow both query and modify for leads:
p4 property -a -n mcp.toolset.reviews.tools -v query_reviews,modify_reviews -g leadsTool-specific overrides can restrict access even when writes are enabled:
p4 property -a -n mcp.toolsets.write -v true
p4 property -a -n mcp.toolset.files.tools -v query_files -g developers
# Result: modify_files is BLOCKED — tool list restrictsNote: Tool-specific overrides cannot bypass write restrictions. The server checks write permissions before evaluating tool lists. If
write=falseis set at any level, write tools are blocked regardless of the tool list.
When a user belongs to multiple groups with conflicting settings, P4 resolves each property to a single value. The MCP server does not perform its own multi-group logic — it uses whichever value P4 returns.
P4's resolution rules for a given property name:
Highest -s (sequence number) wins. This is the primary sort key.
At the same sequence number: user scope > group scope > global scope.
Between groups at the same sequence: the alphabetically-first group name wins.
P4 does not compare values. It picks the winning entry by position, not by content.
Example — groups at the same sequence (default):
p4 property -a -n mcp.toolset.files.enabled -v true -g developers
p4 property -a -n mcp.toolset.files.enabled -v false -g leads
# User in both groups → resolved value is "true"
# Reason: "developers" < "leads" alphabetically, so developers winsSwapping the values would give false — developers still wins regardless of the value.
Example — only one group has a setting:
p4 property -a -n mcp.toolset.files.enabled -v false -g leads
# developers has no setting
# User in developers + leads → resolved value is "false"
# Reason: leads is the only group with a value, so it winsExample — write access:
p4 property -a -n mcp.toolset.files.write -v false -g developers
p4 property -a -n mcp.toolset.files.write -v true -g leads
# User in both groups → resolved value is "false"
# Reason: "developers" < "leads" alphabetically, not because false is "more restrictive"Example — tool lists (no union):
p4 property -a -n mcp.toolset.reviews.tools -v query_reviews -g developers
p4 property -a -n mcp.toolset.reviews.tools -v query_reviews,modify_reviews -g leads
# User in both groups → resolved value is "query_reviews"
# Reason: "developers" wins alphabetically. P4 returns one value, not a union.Example — using -s to control which group wins:
p4 property -a -n mcp.enabled -v false -s1 -g noaccessgroup
p4 property -a -n mcp.enabled -v true -s2 -g accessgroup
# accessgroup wins because -s2 > -s1 (highest sequence wins)Tip: To get predictable results with multiple groups, always use explicit
-svalues rather than relying on alphabetical group name ordering.
Disable a single toolset for all users without affecting others:
p4 property -a -n mcp.toolset.reviews.enabled -v falseThis blocks both query_reviews and modify_reviews for all users. Other toolsets remain unaffected.
Restrict a specific group to read-only without affecting other groups:
p4 property -a -n mcp.toolsets.write -v false -g problematic_groupUsers in other groups retain full write access. If a user belongs to both the restricted group and an unrestricted group, P4's property resolution determines the outcome — typically the alphabetically-first group name wins at equal sequence numbers. Use explicit -s values for predictable results.
The MCP server checks properties in this order. Each property is resolved independently by P4 using the standard resolution rules (highest -s wins, then user > group > global at equal sequence, then alphabetically-first group name).
Check order | Property | MCP server behavior |
1 |
| If resolved value is |
2 |
| If resolved value is |
3 |
| If set, only listed toolsets are available |
4 |
| If resolved value is |
5 |
| If resolved value is |
6 |
| If set, only listed tools within the toolset are available |
Important notes
Each property is resolved to a single value by P4 before the MCP server sees it. P4 uses: highest sequence number (-s) first, then scope (user > group > global) as a tiebreaker, then alphabetical group name. The MCP server does not perform its own multi-group or multi-scope resolution.
mcp.enabled acts as the main switch. When its resolved value is false, all access is blocked.
At the same sequence number, a group or user property overrides a global property. To ensure a global false cannot be overridden, assign it a high -s value.
Scope hierarchy (user > group > global) only applies as a tiebreaker at equal sequence numbers. A group property at -s5 will beat a user property at default sequence or -s1.
When a user belongs to multiple groups, the alphabetically-first group name wins (at equal -s). The winning value is used as-is — P4 does not compare true vs false or pick the "most restrictive" value. Use explicit -s values to control which group takes priority.
Tool-specific overrides (mcp.toolset.<name>.tools) can further restrict access but cannot bypass write restrictions. Write checks are evaluated before tool lists.
Property changes take effect within 60 seconds due to server-side caching, or immediately on a new MCP server connection.
Only the value false (case-insensitive) disables or blocks access. Any other value (including true, 1, yes, or invalid strings) is treated as not blocking.
Actions:
server_info - Get P4 version, uptime, and configuration
current_user - Get current user information and permissions
Use cases - Server diagnostics, user verification, connection testing
Actions:
list - List all workspaces (optionally filtered by user)
get - Get a detailed workspace specification
type - Check workspace type and configuration
status - Check workspace sync status
Parameters: workspace_name, user, max_results
Use cases: Workspace discovery, configuration review, status checking
Actions:
get - Get detailed changelist information (files, description, jobs)
list - List changelists with filters (status, user, workspace)
Parameters: changelist_id, status (pending/submitted), workspace_name, max_results
Use cases: Code review, history tracking, changelist analysis
Actions:
content - Get file content at a specific revision
history - Get file revision history and integration records
info - Get file basic details (type, size, permissions)
metadata - Get file metadata (attributes, filesize, etc.)
diff - Compare file versions (depot-to-depot or mixed)
annotations - Get file annotations with blame information
search - Search for files by name pattern (wildcard matching)
grep - Search for files by content pattern (text search)
Parameters: file_path, file2 (for diff), pattern (for search/grep), case_insensitive (for grep), max_results, diff2 (boolean)
Use cases: Code analysis, file comparison, history tracking, blame analysis, file discovery, content search
Actions:
list - List shelved changes by user or globally
diff - Show differences in shelved files
files - List files in a specific shelf
Parameters: changelist_id, user, max_results
Use cases: Code review, work-in-progress tracking, collaboration
Actions:
list_jobs - List jobs associated with a changelist
get_job - Get detailed job information and status
Parameters: changelist_id, job_id, max_results
Use cases: Defect tracking, requirement traceability, project management
Actions:
list - List all reviews with optional filtering
dashboard - Get current user's review dashboard (my reviews, needs attention)
get - Get detailed review information
transitions - Get available state transitions for a review
files_readby - Get files read status by users
files - Get files in a review (with optional version range)
activity - Get review activity history
comments - Get comments on a review
Parameters:
review_id - Review ID (required for get, transitions, files_readby, files, comments, activity)
review_fields - Comma-separated fields to return (e.g., "id,description,author,state")
comments_fields - Fields for comments (default: "id,body,user,time")
up_voters - List of up voters for transitions
from_version, to_version - Version range for files action
max_results - Maximum results (default: 10)
Use cases: Code review discovery, review status tracking, comment retrieval, review activity monitoring
Actions:
list - List streams with optional filters (path pattern, owner, type)
get - Get a detailed stream specification
children - Get child streams of a given stream
parent - Get the parent stream
graph - Get the full stream graph (parent + children)
integration_status - Get integration status between stream and parent (p4 istat)
get_workspace - Get a workspace spec bound to a stream
list_workspaces - List workspaces bound to a stream
validate_file - Validate file paths against a stream's view
validate_submit - Validate opened files for submit in a stream workspace
check_resolve - Check for pending stream spec conflicts
interchanges - List changelists awaiting integration between streams
Parameters:
stream_name - Stream depot path (required for get, children, parent, graph, check_resolve, interchanges)
stream_path - Path pattern(s) for list (e.g., ["//depot/..."])
filter - Filter expression for list (e.g., "Owner=alice&Type=development")
fields - Fields to return for list (e.g., ["Stream", "Owner", "Type"])
workspace - Workspace name for get_workspace, validate_file, validate_submit
file_paths - File paths for validate_file
view_without_edit - View locked stream spec without opening for edit
at_change - Retrieve historical stream spec at a changelist number
both_directions - Show integration status in both directions
force_refresh - Force istat cache refresh
reverse, long_output, limit - Options for interchanges
unloaded, all_streams, viewmatch - Filters for list
max_results - Maximum results
Use cases: Stream hierarchy exploration, integration status tracking, workspace validation, view compatibility checks
Actions - create, update, delete, switch
Parameters - name, specs (WorkspaceSpec object with View, Root, Options, etc.)
Requires - Read-only mode disabled, appropriate permissions
Use cases - Environment setup, workspace maintenance, branch switching
Actions - create, update, submit, delete, move_files
Parameters - changelist_id, description, file_paths
Safety - Ownership checks, interactive PROCEED/CANCEL elicitation prompt for delete operations with item details
Use cases - Code submission, work organization, file grouping
Actions - add, edit, delete, move, revert, reconcile, resolve, sync
Parameters - file_paths, changelist, force, mode (for resolve operations)
Resolve modes - auto, safe, force, preview, theirs, yours
Use cases - File editing, conflict resolution, workspace synchronization
Actions - shelve, unshelve, update, delete, unshelve_to_changelist
Parameters - changelist_id, file_paths, target_changelist, force
Use cases - Temporary storage, code sharing, backup before experiments
Actions - link_job, unlink_job
Parameters - changelist_id, job_id
Use cases - Defect tracking integration, requirement linking
Actions:
create - Create a new review from a changelist
refresh_projects - Refresh project associations
vote - Vote on a review (up, down, clear)
transition - Change review state (needsRevision, needsReview, approved, committed, rejected, archived)
append_participants - Add reviewers/groups to a review
replace_participants - Replace all participants
delete_participants - Remove participants from a review
add_comment - Add a comment to a review
reply_comment - Reply to an existing comment
append_change - Add a changelist to an existing review
replace_with_change - Replace review content with a changelist
join - Join a review as a participant
leave - Leave a review
archive_inactive - Archive inactive reviews
mark_comment_read / mark_comment_unread - Mark individual comment read status
mark_all_comments_read / mark_all_comments_unread - Mark all comments read status
update_author - Change the review author
update_description - Update review description
obliterate - Permanently delete a review
Parameters:
review_id - Review ID (required for most actions)
change_id - Changelist ID (required for create, append_change, replace_with_change)
description - Review description
reviewers, required_reviewers - Lists of reviewer usernames
reviewer_groups - Reviewer groups with requirements
vote_value - Vote value: up, down, clear
version - Review version for voting
transition - Target state: needsRevision, needsReview, approved, committed, approved:commit, rejected, archived
jobs, fix_status, cleanup - Job linking and cleanup options for transitions
users, groups - Structured participant data for append/replace/delete
body - Comment body text
task_state - Comment task state: open, comment
notify - Notification mode: immediate, delayed
comment_id - Comment ID for replies or marking read/unread
context - Comment context (file, line numbers, content, version)
not_updated_since, max_reviews - Filters for archive_inactive
new_author, new_description - Values for update actions
Use cases: Code review workflow, review state management, collaborative commenting, participant management, review cleanup
Actions:
create - Create a new stream (mainline, development, release, task, virtual, etc.)
update - Update stream properties (name, description, options, paths, parent_view)
delete - Delete a stream
edit_spec - Open stream spec for editing (p4 stream edit)
resolve_spec - Resolve stream spec conflicts
revert_spec - Revert stream spec edits
shelve_spec - Shelve stream spec edits to a numbered changelist
unshelve_spec - Unshelve stream spec edits
copy - Copy changes between parent and child streams
merge - Merge changes between parent and child streams
integrate - Integrate changes with advanced options
populate - Populate a new stream with files (branch)
switch - Switch a workspace to a different stream
create_workspace - Create a new workspace bound to a stream
Parameters:
stream_name - Stream depot path (required for create, update, delete, edit_spec, resolve_spec, revert_spec, switch)
stream_type - Stream type for create: mainline, development, sparsedev, release, sparserel, task, virtual
parent - Parent stream for non-mainline create
name, description - Stream display name and description
options - Stream options: allsubmit/ownersubmit, unlocked/locked, toparent/notoparent, fromparent/nofromparent, mergedown/mergeany
parent_view - Parent view treatment: inherit or noinherit
paths, remapped, ignored - Stream view mappings
changelist - Changelist for spec editing or propagation operations
resolve_mode - Resolve mode for resolve_spec: auto, accept_theirs, accept_yours
parent_stream - Override parent for propagation (-P flag)
branch - Branch spec for integrate/populate (-b flag)
file_paths - File paths for propagation
preview - Preview only, no changes (-n flag)
force - Force operation (-f flag)
reverse - Reverse direction (-r flag)
max_files - Limit files processed (-m flag)
quiet - Suppress informational messages (-q flag)
output_base - Show base revision with scheduled resolve (-Ob flag for merge/integrate) or list files created (-o flag for populate)
virtual - Copy using virtual stream (-v flag, copy only)
schedule_branch_resolve - Schedule branch resolves instead of automatic branching (-Rb flag, integrate only)
integrate_around_deleted - Integrate around deleted revisions (-Di flag, integrate only)
skip_cherry_picked - Skip cherry-picked revisions already integrated (-Rs flag, integrate only)
source_path, target_path - Source and target paths for populate
workspace - Workspace name for switch
workspace_name, root, host, alt_roots - Workspace creation parameters
Safety: Stream existence validation, locked stream detection, bound workspace warnings, open file checks for view-affecting changes
Use cases: Stream creation and management, branch propagation (merge/copy/integrate), spec conflict resolution, workspace provisioning
Warnings in tool responses
When a P4 command produces a benign informational or warning message (for example,
file(s) up-to-dateorfile not on client), the tool returns a successstatusand includes the message text in an optional top-levelwarningslist. The field appears only when there is at least one warning. Genuine failures are unaffected and still return an errorstatuswith the existingcodeanderrorfields.
Log locations:
Application log: logs/p4mcp.log - Main server operations and errors
Session logs: logs/sessions/*.log - Individual session activities are recorded only when the --allow-usage flag is specified in the server's startup arguments.
Privacy-first approach:
Disabled by default: No data collection without explicit consent
Consent-gated: First-run prompt for telemetry permission
Transparent: Clear explanation of data collected
Revocable: Easy opt-out at any time
Data collected (if consented):
Tool usage frequency (anonymized)
Error rates and types (no personal data)
Performance metrics
Feature adoption statistics
P4 server version
Data not collected:
File contents or names
P4 Server details except version
User credentials or personal information
Specific project information
Control:
Usage data is only collected if the --allow-usage argument is provided at startup.
Symptoms: OS cannot find or execute the binary; error includes ENOENT or "No such file or directory".
Solutions:
Check the path: Make sure the command field uses the correct absolute path for your OS:
macOS/Linux: /absolute/path/to/p4-mcp-server
Windows: C:\absolute\path\to\p4-mcp-server.exe
Ensure the binary exists and is executable:
macOS/Linux:
ls -l /absolute/path/to/p4-mcp-server && chmod +x /absolute/path/to/p4-mcp-serverWindows:
dir C:\absolute\path\to\p4-mcp-server.exeOn Windows, ensure the binary is not blocked:
Right-click the .exe file, select Properties, and if present, click Unblock.
Symptoms: Cannot connect to P4 Server
Solutions:
Verify the P4PORT environment variable: echo $P4PORT (macOS) or echo $env:P4PORT (Windows)
Test the direct connection: p4 info
Check server availability: ping perforce.example.com
Verify the port and protocol (ssl: prefix for SSL connections).
Symptoms: SSL trust errors when connecting to the P4 server Solutions:
Trust the server: p4 trust -f -y
Check trust status: p4 trust -l
For persistent issues, verify the SSL configuration.
Symptoms: CERTIFICATE_VERIFY_FAILED errors when using review tools
Solutions:
System trust store: By default, the server uses the OS trust store via truststore. Ensure your corporate CA is installed in the OS certificate store.
Custom CA bundle: To use a custom CA certificate, you must first set P4MCP_TLS_CA_MODE=certifi (to disable truststore), then provide the CA path via --ca-bundle /path/to/ca.pem or P4MCP_CA_BUNDLE. In the default system mode, truststore overrides custom CA bundles and they are silently ignored.
Disable verification: Use --ssl-no-verify or set P4MCP_SSL_VERIFY=false (not recommended for production). This works in both TLS modes.
Note: These SSL settings only apply when the Swarm URL uses HTTPS. If Swarm is configured with an
http://URL, SSL verification is not performed and these settings have no effect.
Symptoms: Authentication failures
Solutions:
Log in to P4: p4 login -a
Check login status: p4 login -s
Verify the user exists: p4 users -m 1 your_username
For persistent issues, check password or use ticket-based authentication.
Symptoms: Login failures
Solutions:
Reset the password through a P4 administrator.
Use ticket-based authentication: p4 login -a
Verify the username is correct: p4 info
Symptoms: Workspace not found errors
Solutions:
List the available workspaces: p4 clients
Verify the P4CLIENT environment variable.
Create a workspace if needed: p4 client workspace_name
Check the workspace ownership: p4 client -o workspace_name
Symptoms: Files are outside the workspace mapping
Solutions:
Check the client view: p4 client -o workspace_name
Update the workspace mapping to include the required paths.
Use p4 where file_path to check the mapping.
Symptoms: Insufficient permissions for operations
Solutions:
Check the file ownership: p4 opened file_path
Verify the user permissions: p4 protects file_path
Ensure proper group membership.
For admin operations, verify admin permissions.
Symptoms: Exclusive lock conflicts
Solutions:
Check who has the file open: p4 opened file_path
Contact the user to resolve conflicts.
Admin can force operations if necessary.
Symptoms: Long response times
Solutions:
Use the max_results parameter to limit the query size.
Use specific file paths instead of wildcards.
Check network connectivity to P4.
Monitor server performance.
Symptoms: High memory usage
Solutions:
Reduce max_results for large queries.
Process files in batches.
Restart the MCP server periodically for long-running sessions.
Symptoms: Conflict with built-in or other MCP tools Solutions:
Disable any built-in or conflicting MCP server tools in your environment or configuration.
Ensure the P4 MCP server tools are properly registered and enabled.
Restart the MCP server after applying configuration changes to load the correct tools.
Symptoms: Invalid context or outdated session history Solutions:
Provide a P4-related context when writing prompts.
Start a new session if the existing session is old or contains conflicting prompt history.
Authentication: Ensure valid login before MCP operations.
Workspace mapping: Verify client views include target files.
Permissions: Check user and file permissions for write operations.
Network: Verify connectivity for remote P4 Servers.
Check the logs: Always check logs/p4mcp.log first.
Test P4: Ensure p4 info works before troubleshooting MCP.
Report issues to the community: Report issues with log excerpts and environment details.
Perforce P4 MCP Server is a community supported project and is not officially supported by Perforce. Pull requests and issues are the responsibility of the project's moderator(s); this may be a vetted individual or team with members outside of the Perforce organization. All issues should be reported and managed via GitHub (not via Perforce's standard support process).
We welcome contributions to the P4 MCP Server project.
This project is licensed under the MIT License. See LICENSE for details.
This project includes third-party components. Their licenses and attributions are listed in THIRD-PARTY-NOTICES.
Create/delete changelists, update changelists and organize files/jobs (WRITE permission)
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Changelist modification action: create makes new changelist, update modifies description, submit commits changes, delete removes changelist, move_files reorganizes files between changelists | |
| file_paths | No | File paths - required for move_files action | |
| description | No | Changelist description - required for create, optional for update | |
| changelist_id | No | Changelist ID - required for most actions except create |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It mentions 'WRITE permission' and lists actions, but does not explain side effects (e.g., deletion consequences, submission requirements) or dependencies beyond what the schema provides.
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 one sentence, concise and front-loaded with the main purpose. It could be slightly more structured (e.g., bullet list of actions), but it is efficient 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?
Given the tool's complexity (4 parameters, multiple action enums, output schema exists), the description covers the high-level purpose but lacks details on conditional parameter requirements and workflow steps. Still, it is largely sufficient for an agent with schema access.
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 100%, so baseline is 3. The description adds minimal value beyond the schema; it repeats action types but does not clarify parameter interactions or conditional requirements (e.g., file_paths needed for move_files).
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 actions (create, delete, update, organize) on changelists, with 'WRITE permission' indicating the kind of operations. It distinguishes from sibling tools like query_changelists and other modify tools.
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 vs. alternatives. The description implies it is for changelist modifications, but does not mention when not to use it or suggest alternatives like query_changelists for reading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add, edit, move, delete, revert, reconcile, resolve, and sync files (WRITE permission)
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Resolve mode: auto(-am), safe(-as), force(-af), preview(-n), theirs(-at), yours(-ay) | auto |
| force | No | Force operation - use with caution | |
| action | Yes | File modification action | |
| changelist | No | Changelist ID or 'default' | default |
| file_paths | No | Full depot or client or local paths | |
| source_paths | No | Source paths - required for move action | |
| target_paths | No | Target paths - required for move action |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions 'WRITE permission' but does not explain side effects, destructive potential, or what happens during actions like revert or reconcile. The schema reveals modes and force flags, but the description omits behavioral context.
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 listing actions and permission, which is concise and has no wasted words. However, it lacks structure such as separating actions or providing additional context. It is efficient but could be more 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 the tool has 8 actions, 7 parameters, and an output schema, the description is very incomplete. It does not explain the differences between actions, when to use each mode, or what the return value looks like. The output schema is present but unused in the description.
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 100%, so the schema already documents all parameters. The description adds no additional semantic context beyond the schema's parameter descriptions. Baseline of 3 is appropriate.
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 explicitly lists all supported file modification actions (add, edit, move, delete, revert, reconcile, resolve, sync) and specifies 'WRITE permission', clearly indicating it is a write operation for files. This distinguishes it from sibling tools like query_files (read-only) and other modify tools.
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 actions but does not provide explicit guidance on when to use this tool versus alternatives like modify_changelists or query_files. It implies file modification contexts but lacks when-not instructions or differential advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Link or unlink jobs (WRITE permission)
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Job modification action: link_job associates job with changelist, unlink_job removes job association | |
| job_id | Yes | Job ID - required for link_job/unlink_job | |
| changelist_id | Yes | Changelist ID - required for link_job/unlink_job |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description informs that the tool requires WRITE permission and performs linking/unlinking, but it does not disclose behavioral details such as what happens to existing associations, whether the operation is reversible, or any side effects. The schema's action enum descriptions provide minimal clarity, but the description itself is insufficient.
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, front-loaded sentence with no extraneous information. Every word contributes to stating the tool's purpose and permissions.
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 having an output schema and fully described parameters, the description is too sparse. It omits any mention of return values, prerequisites, or behavioral context that would help an agent understand the tool's full operation. The tool's mutation nature and lack of annotations increase the need for more 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 100% with verbose parameter descriptions that fully explain each parameter's role. The tool description adds no additional meaning beyond what the schema already provides, meeting the baseline expectation.
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 links or unlinks jobs, specifying the resource (jobs) and action. It distinguishes from siblings like query_jobs (read) by implying write operations, although it does not explicitly differentiate from other modify tools.
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 includes a permission hint (WRITE permission) but provides no guidance on when to use this tool versus alternatives like modify_changelists, which might also handle job associations. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create/update/delete reviews (WRITE permission)
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Comment body (required for add_comment, reply_comment) | |
| jobs | No | Associated job IDs for transition | |
| action | Yes | Review modification action. To delete/obliterate review, use 'obliterate' action which requires approval | |
| notify | No | Notification mode | |
| cleanup | No | Perform cleanup for approved:commit/committed transitions | |
| version | No | Review version (optional for vote) | |
| change_id | No | Changelist ID (required for create, append_change, replace_with_change) | |
| review_id | No | Review ID (required for most actions except create, archive_inactive) | |
| reviewers | No | List of reviewers | |
| comment_id | No | Parent comment ID (reply_comment, mark_comment_read/unread) | |
| fix_status | No | Job fix status when transitioning | |
| new_author | No | New author username (update_author) | |
| task_state | No | Task state | |
| transition | No | Transition target state | |
| vote_value | No | Vote value | |
| description | No | Review description (optional on create) | |
| max_reviews | No | Maximum number of inactive reviews to archive (0 = no limit) | |
| comment_version | No | Review version for comment attachment | |
| new_description | No | New review description (update_description) | |
| comment_file_path | No | File path for inline comment | |
| comment_left_line | No | Left diff line number for inline comment | |
| not_updated_since | No | ISO date (YYYY-MM-DD) threshold for archive_inactive | |
| comment_right_line | No | Right diff line number for inline comment | |
| required_reviewers | No | List of required reviewers | |
| reviewer_group_names | No | List of reviewer group names | |
| participant_user_names | No | List of participant usernames | |
| participant_group_names | No | List of participant group names | |
| reviewer_groups_required | No | List of required reviewer groups | |
| participant_users_required | No | List of required participant usernames | |
| participant_groups_required | No | List of required participant groups |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It only mentions 'WRITE permission' and does not disclose side effects, error conditions, idempotency, or behavior for actions like 'obliterate' (which requires approval), leaving agent uninformed.
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, which is concise but at the expense of completeness. For a tool with 30 parameters and 22 actions, this is under-specification rather than efficient conciseness.
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 the presence of an output schema, the description lacks context on how to choose among the many actions, required permissions beyond WRITE, and behavioral details. The tool is complex, and the description is too brief to be 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 input schema has 100% description coverage, so the schema already documents parameters. The description adds no value for parameter semantics; it does not summarize key parameters or guide selection among the many parameters. Baseline 3 would be too generous given the complexity.
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 'Create/update/delete reviews (WRITE permission)', clearly indicating the verb and resource. However, it does not convey the full range of 22 different actions available (e.g., vote, transition, comment), making it slightly vague for the tool's actual scope.
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 this tool versus siblings like `modify_changelists` or `modify_jobs`. It mentions WRITE permission but lacks context on specific scenarios or prerequisites for individual actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create/delete, update shelves and unshelve files (WRITE permission)
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Force operation - use with caution | |
| action | Yes | Shelve modification action: shelve stores files to shelf, unshelve restores files from shelf, update modifies shelved files, delete removes shelf, unshelve_to_changelist restores to specific changelist | |
| file_paths | No | File paths for shelve/unshelve/update/delete | |
| changelist_id | Yes | Changelist ID | |
| target_changelist | No | Target changelist for unshelve operations | default |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behaviors. It mentions 'WRITE permission' and lists actions (shelve, unshelve, update, delete, unshelve_to_changelist), but lacks details on consequences (e.g., what 'force' does, data loss risks). The warning 'use with caution' is in the schema, not description.
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 front-loaded sentence that efficiently conveys the core functionality. It is concise with no wasted words, though it could benefit from slightly more context.
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, no annotations, and an output schema, the description is minimal. It covers the basics but does not explain return values (though output schema exists) or detail nuances like the difference between 'unshelve' and 'unshelve_to_changelist'. 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 description coverage is 100%, so the baseline is 3. The description merely summarizes the actions (create/delete, update, unshelve) already detailed in the 'action' enum. It adds no new meaning 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 tool's purpose: 'Create/delete, update shelves and unshelve files', using specific verbs and the resource 'shelves'. It also notes 'WRITE permission', distinguishing it from the read-only sibling 'query_shelves'.
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 explicitly state when to use this tool versus alternatives. It only implies usage for shelf modifications. Sibling names like 'query_shelves' suggest a read/write split, but no clear guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create/update/delete streams, edit/resolve/revert/shelve stream specs, copy/merge/integrate/populate between streams, switch workspace, create stream workspace (WRITE permission)
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | Host restriction (create_workspace) | |
| name | No | Short display name for the stream | |
| root | No | Workspace root directory (create_workspace) | |
| force | No | Force operation | |
| paths | No | Stream view paths (e.g. ['share ...', 'isolate dir/...']) | |
| quiet | No | Suppress informational messages (-q flag) | |
| action | Yes | Stream modification action: 'create'/'update'/'delete' a stream, 'edit_spec'/'resolve_spec'/'revert_spec'/'shelve_spec'/'unshelve_spec' for spec editing, 'copy'/'merge'/'integrate'/'populate' for propagation, 'switch' workspace stream, 'create_workspace' for a stream | |
| branch | No | Branch spec name for integrate/populate (-b flag) | |
| parent | No | Parent stream (required for non-mainline create) | |
| ignored | No | Ignored paths | |
| options | No | Stream options: 'allsubmit/ownersubmit unlocked/locked toparent/notoparent fromparent/nofromparent' | |
| preview | No | Preview only, don't make changes (-n flag) | |
| reverse | No | Reverse direction (-r flag) | |
| virtual | No | Copy using virtual stream (-v flag, copy only) | |
| remapped | No | Remapped paths | |
| alt_roots | No | Alternate root paths (create_workspace) | |
| max_files | No | Limit number of files processed (-m flag) | |
| workspace | No | Workspace name for switch | |
| changelist | No | Changelist for edit_spec, shelve_spec, unshelve_spec, or propagation, 'default' not allowed for edit_spec/shelve_spec/unshelve_spec | |
| file_paths | No | File paths for propagation | |
| description | No | Stream or workspace description | |
| output_base | No | Show base revision with each scheduled resolve (-Ob flag for merge/integrate) or display list of files created (-o flag for populate) | |
| parent_view | No | Parent view treatment: 'inherit' or 'noinherit' | |
| source_path | No | Source path for populate | |
| stream_name | No | Stream depot path (e.g. '//depot/main'). Also used as -S flag for propagation. | |
| stream_type | No | Stream type (required for create): mainline, development, sparsedev, release, sparserel, task, virtual | |
| target_path | No | Target path for populate | |
| resolve_mode | No | Resolve mode for resolve_spec: 'auto', 'accept_theirs', 'accept_yours' | |
| parent_stream | No | Override parent stream for propagation (-P flag) | |
| workspace_name | No | Workspace name to create (create_workspace) | |
| target_changelist | No | Target changelist for unshelve_spec | |
| skip_cherry_picked | No | Skip cherry-picked revisions already integrated (-Rs flag) | |
| schedule_branch_resolve | No | Schedule 'branch resolves' instead of branching new target files automatically (-Rb flag) | |
| integrate_around_deleted | No | Integrate around deleted revisions (-Di flag) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description mentions 'WRITE permission' but does not disclose side effects, destructive potential, or other behavioral traits. For a tool with many mutating actions (delete, force, reverse, etc.), this is insufficient.
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 that lists actions with commas. It is relatively concise but could be better structured (e.g., bullet points) to improve readability. No wasted words, but the list approach feels rushed.
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 (34 parameters, 14 action types, output schema present), the description is too sparse. It does not explain return values, prerequisites for actions, or common usage patterns. The agent needs more context to use this tool effectively.
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 100%, so the schema already describes each parameter. The description adds minimal value beyond grouping actions; it does not clarify parameter interactions or provide usage examples. Baseline 3 is appropriate.
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 lists specific actions (create, update, delete, edit_spec, etc.) and resources (streams, workspace), making it clear what the tool does. It distinguishes from sibling query tools like query_streams by implying mutation. However, the list format is somewhat cluttered, and the phrase '(WRITE permission)' at the end adds context.
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., modify_workspaces for workspace creation). No when-not-to-use or prerequisite info. The description assumes the agent knows which action to pick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create/delete workspace, Update workspace specs, and switch active workspace (WRITE permission)
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Workspace modification action: create makes new workspace, delete removes workspace, update modifies workspace spec, switch changes active workspace | |
| workspace_name | Yes | Workspace name | |
| workspace_root | No | Root path of the workspace | |
| workspace_view | No | View mappings in depot-to-client format | |
| workspace_options | No | Workspace options | noallwrite noclobber nocompress unlocked nomodtime normdir |
| workspace_line_end | No | Line ending style (local, unix, win, mac) | local |
| workspace_description | No | Workspace description |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It mentions 'WRITE permission' but does not disclose destructive nature of delete, whether updates are partial or full, or side effects of switching workspaces. Critical behavioral traits are missing.
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 concise sentence that front-loads the main actions. It is clear and waste-free, though could benefit from a list format for 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?
Given the output schema exists, the description adequately covers the tool's purpose and permission. However, it lacks context on prerequisites, consequences of each action, and when to use specific actions, leaving gaps for a multi-action 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 100%, so the input schema already documents all parameters. The description adds only a summary of actions and permission hint, not providing additional semantic context beyond what the schema offers.
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 performs create, delete, update, and switch actions on workspaces, which are distinct from sibling tools like query_workspaces (read-only) and modify_streams (different resource). The mention of 'WRITE permission' further clarifies the action type.
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 the tool is for modifying workspaces but offers no explicit guidance on when to use this tool over siblings (e.g., query_workspaces for reading) or which action to select. No usage context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get changelist details and list changelists (READ permission)
| Name | Required | Description | Default |
|---|---|---|---|
| user | No | Filter by user - for list action | |
| action | Yes | Changelist query action: get retrieves specific changelist details, list returns all changelists matching filters | |
| status | No | Filter by status - for list action | |
| depot_path | No | Filter by depot path - for list action | |
| max_results | No | Maximum number of results to return. Bounds the 'list' action and also caps open files for get('default') via 'p4 opened -m N'. Omit for unbounded results. | |
| changelist_id | No | Changelist ID - required for get action | |
| workspace_name | No | Filter by workspace - for list action |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description lacks disclosure of behavioral traits beyond READ permission. Does not mention idempotency, safety, side effects, or output characteristics.
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 wasted words. But could be slightly more informative without losing conciseness.
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 7 parameters and existing output schema, description is minimal but functional. Lacks details on action differentiation or typical use cases.
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 covers all 7 parameters (100% coverage). Description adds no additional meaning beyond schema. Baseline 3 applies.
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 gets changelist details and lists changelists. (READ permission) distinguishes it from modify tools. Specific verb+resource.
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?
Indicates read-only usage via '(READ permission)', but does not explicitly state when not to use or mention alternative tools like modify_changelists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get file content, history, info, diff, annotations, search by name, grep by content (READ permission)
| Name | Required | Description | Default |
|---|---|---|---|
| diff2 | No | Use p4 diff2 for depot-to-depot diff, false for mixed diff | |
| file2 | No | Second file path - required for diff action | |
| action | Yes | File query action, metadata includes extra information like optional attributes and file size | |
| pattern | No | Search or grep pattern - required for search and grep actions | |
| file_path | Yes | Primary file path - required for all actions | |
| max_results | No | Maximum number of results to return. Bounds history/search/grep and also caps fstat info/metadata via 'p4 fstat -m N'. Omit for unbounded info/metadata results. | |
| case_insensitive | No | Case-insensitive matching for grep action |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the burden of disclosing behavior. It mentions 'READ permission' but fails to state what happens if the file does not exist, whether the tool is destructive, rate limits, or other side effects. The listed actions imply read-only, but no further traits are disclosed.
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 that packs multiple actions and permissions. While concise, it lacks structure (e.g., bullet points) and front-loads the most important information. It is not overly verbose, but could be better organized for quick scanning by an AI agent.
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 (7 parameters, 8 actions, enums) and the presence of an output schema, the description should provide richer context like action-specific behavior, error handling, or examples. It does not explain how to choose among actions or how parameters interact (e.g., file2 for diff). This leaves gaps in 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 100%, so the baseline is 3. The tool description adds minimal value beyond the schema: it lists actions and notes permissions, but does not clarify parameter relationships or usage nuances that the schema already covers. For instance, the schema already describes max_results bounding and file_path examples.
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 retrieves file content, history, info, diff, annotations, and performs search by name and grep by content. It lists distinct actions under a single verb 'Get', making the purpose specific. Sibling tools like modify_files or query_streams have different resources or operations, so this tool is well-distinguished.
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 guidance on when to use this tool versus alternatives (e.g., query_files vs query_changelists) or among its own actions. There are no explicit when-to-use or when-not-to-use instructions, and no exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get jobs from changelist and get job details (READ permission)
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Job query action: list_jobs returns jobs linked to changelist, get_job retrieves specific job details | |
| job_id | No | Job ID - required for get_job action | |
| max_results | No | Maximum number of results to return | |
| changelist_id | No | Changelist ID - required for list_jobs action |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'READ permission', which is useful given no annotations. However, it does not disclose other behavioral traits like nondestructiveness, rate limits, or whether changes affect other data.
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?
Extremely concise: two brief clauses that front-load the verb and resource, with no extraneous 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 the presence of an output schema and the straightforward nature of a query tool, the description covers the main actions adequately. Missing details like permission levels or pagination behavior, but acceptable for a simple 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 100% schema description coverage, the schema already explains each parameter. The description adds minimal extra meaning (e.g., 'from changelist'), but does not significantly enhance understanding 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 specifies the main actions (list jobs from changelist, get job details) and indicates read-only via 'READ permission'. It clearly distinguishes from sibling tools that operate on other resources like reviews or files.
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 versus alternatives like `query_reviews` or `modify_jobs`. No conditions or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get review details and list reviews (READ permission). Open review - state is 'approved but pending=true' or 'needsReview' or 'needsRevision'. Closed review - state is 'approved but pending=false' or 'rejected' or 'archived'.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Review ID to seek to for pagination (list action). Reviews up to and including this ID are excluded. | |
| state | No | Filter by review state(s) (list action). Valid: needsRevision, needsReview, approved, approved:isPending, approved:commit, approved:notPending, rejected, archived | |
| action | Yes | Review query action: list all reviews, dashboard for current user, get specific review, transitions, files_readby, files, comments, activity | |
| fields | No | List of fields to return for list/get actions | |
| keywords | No | Search keyword(s) to filter reviews (list action). Use with keywords_fields. | |
| projects | No | Filter by project name(s) (list action) | |
| review_id | No | Review ID - required for get, transitions, files_readby, files, comments, activity actions | |
| up_voters | No | List of up voters for transitions action | |
| to_version | No | Ending version for files action | |
| max_results | No | Maximum number of results to return | |
| from_version | No | Starting version for files action | |
| result_order | No | Set to 'updated' to return most recently updated reviews first (list action) | |
| after_updated | No | Return reviews updated on the day before this date/time in seconds since epoch (list action). Mutually exclusive with 'after'. | |
| comments_fields | No | Comma-separated list of fields to return for comments action | id,body,user,time |
| keywords_fields | No | Fields to search keywords in (list action). Valid: changes, author, participants, hasReviewer, description, updated, projects, state, testStatus, pending, groups, id | |
| include_transitions | No | Include allowed state transitions in get action response |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure burden. It explains open vs closed states and permission, which is helpful. However, it does not disclose other behavioral traits like pagination, action-specific behavior, or result structure. The schema covers parameters but not 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 very concise—two sentences. The first sentence states purpose, the second adds valuable state definitions. No unnecessary wording.
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 (16 parameters, 1 required, multiple actions, output schema exists), the description is too sparse. It does not guide how to use different actions (list, get, etc.) or differentiate from other query_ tools. Significant gaps remain.
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 100%, so baseline is 3. The description does not add parameter-specific meaning beyond what the schema provides. The state definitions in description are about values, not 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?
The description clearly states the tool's purpose: 'Get review details and list reviews (READ permission).' It distinguishes from sibling tools like modify_reviews (for writing) and other query_ tools for different resources.
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 read-only usage via '(READ permission)' but does not explicitly state when to use this tool vs alternatives like modify_reviews or other query tools. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get server info and current user information (READ permission)
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Server query action: server_info returns P4 server metadata and version, current_user returns authenticated user details and permissions |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'READ permission', indicating non-destructive behavior, which is useful. However, it does not disclose any other traits like response size limits, rate limits, or authentication requirements. The behavior is simple and the action enum fully specifies the operations, so a score of 3 is appropriate.
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 that efficiently conveys the purpose. It is not verbose and front-loads the key information. However, the title is null, and the description could be slightly expanded to improve usability without being wasteful.
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 tool with one parameter and a probable output schema (not shown but implied), the description covers the essential purpose and permission. The input schema covers parameter semantics. It does not explain return values, but the output schema likely fills that gap. Overall, it is adequate for straightforward usage.
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 100%, with the single parameter 'action' fully documented in the input schema, including explanations of both enum values. The tool description adds only 'READ permission', which is implied by the action names. No parameter details beyond the schema are provided, so baseline 3 applies.
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 function: 'Get server info and current user information (READ permission)'. It specifies the verb 'Get' and the resources. The input schema further distinguishes two actions (server_info, current_user), making the purpose unambiguous. It also differentiates from sibling tools like query_streams and modify_streams by focusing on server-level metadata and user info.
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 this tool versus alternatives. While it mentions 'READ permission', it does not explain when query_server is preferred over other query tools (e.g., query_streams). No exclusions or context for usage are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List shelves, get shelve diff and files (READ permission)
| Name | Required | Description | Default |
|---|---|---|---|
| user | No | Filter by user - for list action | |
| action | Yes | Shelve query action: list returns all shelved changelists, diff shows shelved file differences, files lists files in shelved changelist | |
| max_results | No | Maximum number of results to return | |
| changelist_id | No | Changelist ID - required for diff and files actions |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It mentions READ permission, which is basic transparency, but does not disclose rate limits, auth details beyond permission, or specific 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 a single concise sentence that captures the tool's core functionality. No extraneous 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?
Output schema exists, so return format is covered. However, the description lacks context on pagination, error handling, or typical use cases for each action, leaving some gaps for complex usage.
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 100% coverage, so description adds minimal value beyond explaining the action parameter. The 'READ permission' tag does not enhance parameter understanding.
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 tool lists shelves, gets diff, and gets files, specifying READ permission. It distinguishes from sibling modify_shelves, which indicates a read-only purpose.
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?
Indicates READ permission, implying read-only usage, and the schema provides action enum. However, it lacks explicit guidance on when to use this versus read-only query tools for changelists or files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query streams: list, get spec, children/parent/graph, integration status, workspaces, validate files, check resolve, interchanges (READ permission)
| Name | Required | Description | Default |
|---|---|---|---|
| user | No | Filter workspaces by user (list_workspaces) | |
| limit | No | Max changelists (interchanges) | |
| action | Yes | Stream query action: 'list' streams, 'get' stream spec, 'children'/'parent'/'graph' of a stream, 'integration_status' (p4 istat), 'get_workspace'/'list_workspaces', 'validate_file'/'validate_submit' against stream view, 'check_resolve' for pending spec conflicts, 'interchanges' between streams | |
| fields | No | Fields to return for 'list' (e.g. ['Stream', 'Owner', 'Name', 'Type']) | |
| filter | No | Filter expression string for 'list' (-F flag). Supports &, |, and parentheses. E.g. 'Parent=//Ace/MAIN&(Type=development|Type=release)' | |
| reverse | No | Reverse comparison direction (interchanges) | |
| template | No | Template workspace for get_workspace | |
| unloaded | No | Include unloaded streams/workspaces | |
| at_change | No | Changelist number for historical stream spec | |
| viewmatch | No | Single depot file path to filter streams whose views contain this path | |
| workspace | No | Workspace name for get_workspace, validate_file, validate_submit | |
| changelist | No | Changelist for validate_submit | |
| file_paths | No | File paths for validate_file or interchanges | |
| all_streams | No | Include virtual streams in 'list' results | |
| long_output | No | Full changelist descriptions (interchanges) | |
| max_results | No | Maximum number of results to return. Bounds 'list' and 'list_workspaces' and also caps 'children' via 'p4 streams -m N'. Omit for unbounded results. | |
| stream_name | No | Stream depot path (e.g. '//depot/main'). Required for most actions. | |
| stream_path | No | Stream path pattern(s) for 'list' (e.g. ['//depot/...']) | |
| force_refresh | No | Force istat to assume cache is stale and search for pending integrations (-c flag) | |
| both_directions | No | Show integration status in both directions (-a flag for integration_status) | |
| view_without_edit | No | View locked stream without opening for edit (-v flag) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully convey behavioral traits. It only states 'READ permission', implying read-only, but lacks details on side effects, rate limits, output format, or the fact that different actions require different parameters.
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 that efficiently lists all actions, but it lacks structure (e.g., bullet points or grouping) for 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?
Given the tool's complexity (21 parameters, 12 actions, output schema exists), the description is far too sparse. It does not clarify which parameters apply to which action, nor does it mention the return format or that the tool supports multiple disparate operations.
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 100%, so baseline is 3. The description does not add any parameter-specific information; it only lists actions, which is already implied by the enum 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 explicitly enumerates all supported actions (list, get spec, children/parent/graph, integration status, workspaces, validate files, check resolve, interchanges) and indicates READ permission, clearly distinguishing it from sibling write tools like modify_streams.
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 on when to use this tool versus alternatives (e.g., query_workspaces or query_files). There is no mention of prerequisites, exclusions, or context for specific actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get workspace details, list workspaces, check type and status (READ permission)
| Name | Required | Description | Default |
|---|---|---|---|
| user | No | Filter by user - optional for list action | |
| action | Yes | Workspace query action: list returns all workspaces matching filters, get retrieves specific workspace spec, type identifies workspace category, status shows opened files and sync state | |
| max_results | No | Maximum number of results to return | |
| workspace_name | No | Workspace name - required for get, type, status actions |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavioral traits. It mentions 'READ permission' indicating non-destructiveness but lacks details on side effects, rate limits, or error behavior. Minimal transparency beyond the read-only hint.
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 with no redundancy. However, it is very terse for a tool with 4 parameters and multiple actions; more structured front-loading of key information (e.g., required parameter usage) would improve usability.
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 (4 parameters, 4 action enums) and the presence of an output schema, the description fails to explain pagination, error scenarios, or prerequisites beyond 'READ permission'. It leaves gaps despite the schema covering parameter semantics.
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 100%, so baseline is 3. The description repeats the action descriptions already in the schema (e.g., 'list returns all workspaces matching filters') without adding new meaning or clarifying parameter interactions 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?
Description clearly states 'get', 'list', 'check' actions on workspaces, and explicitly mentions 'READ permission', distinguishing it from sibling tools like 'modify_workspaces'. It covers all four actions in the input schema.
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 a read-only use case via 'READ permission' but does not explicitly state when to use this tool versus alternatives like query_streams or modify_workspaces. No when-not-to-use or conditional guidance provided.
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.
v2026.3.2996147modify_changelistsmodify_filesmodify_jobsmodify_reviewsmodify_shelvesmodify_streamsmodify_workspacesquery_changelistsquery_filesquery_jobsquery_reviewsquery_serverquery_shelvesquery_streamsquery_workspacesEvery tool targets a distinct resource and action, with clear separation between query_ (read) and modify_ (write) operations. There is no overlap or ambiguity between tools.
Tools follow a consistent 'verb_resource' pattern: 'query_' for reads and 'modify_' for writes, applied across all resource types. This pattern is predictable and intuitive.
With 15 tools, the server is well-scoped for a version control system. Each tool covers a distinct operation area (streams, workspaces, files, changelists, shelves, jobs, reviews, server info), without excess or deficiency.
The tool set provides comprehensive CRUD-like operations for core Perforce resources. Minor gaps exist (e.g., no admin or label operations), but the essential workflows for typical usage are well-covered.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A Model Context Protocol (MCP) application for automated GitHub PR analysis and issue management.…
Model Context Protocol server for Studex tools, notifications, and profile integrations
Read and write Mission Control state via MCP — projects, tasks, subtasks, templates, status updates.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/perforce/p4mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
