Click on "Deploy 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., "@rig-bridge Open my project workspace at ~/projects/website and show its file tree."
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.
A small MCP server for working on your computer from an AI assistant. The assistant holds the conversation and decides what to do. The server calls Pi's actual file and shell tools and returns their results, without starting another model session.
One OS account, one computer, one server process. Workspaces select directories so several projects and conversations can share that process.
Requires Node.js 24+, npm, Git, and a working bash installation. Install the checkout's pinned dependencies:
git clone https://github.com/dna113p/rig-bridge.git
cd rig-bridge
npm ci --ignore-scripts
npm run check
npm run servePi is installed as a dependency. A separate Pi CLI installation or model API key is unnecessary for the server's own tool execution.
HTTP listens at http://127.0.0.1:8767/mcp. On first start, it generates an owner-only bearer file at ~/.local/state/rig-bridge/http-authorization (or under XDG_STATE_HOME). The credential is never printed. The file contains the complete value to send in the Authorization header, including Bearer.
Connect your MCP client or authenticated tunnel/proxy to that HTTP endpoint and supply the header. The proxy must preserve the local target's Host and omit browser Origin. A remote assistant needs a connection that can reach this local endpoint. Tunnel provisioning is separate from this package.
Optional flags:
npm run serve -- --port 9000 --state-dir /absolute/private/state
npm run serve -- --token-file /absolute/existing/bearer-fileAn explicitly supplied bearer file must already exist, have owner-only permissions, and contain Bearer followed by at least 43 base64url characters. Keep it outside the checkout.
For a client that launches a local stdio MCP server, use the absolute Node executable and src/cli.ts paths in its configuration:
{
"mcpServers": {
"rig-bridge": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/rig-bridge/src/cli.ts"]
}
}
}Stdio uses the local client's process access. Use HTTP when multiple clients should share one server. This checkout runs TypeScript directly under Node 24; global npm installation is not an advertised installation path.
Related MCP server: lnwjud
Tool | Purpose |
| Open a directory; omit |
| Close the workspace and cancel its active calls. Repeating close is harmless. |
| Read text or supported images through Pi. Returns a file revision. |
| List directory contents. |
| Find files by glob. |
| Search file contents. |
| Create or replace a file. |
| Apply Pi's targeted text replacements and return its diff. |
| Run a command and return output, exit status, and truncation details. |
| Inspect available Pi skills or get the full instructions and metadata for a specific skill. |
Text results are available in both MCP content and structuredContent.output, alongside structured metadata such as revisions and exit codes. Clients consuming only structured results can read file contents, search matches, command output, and error messages from output. Pi's truncation notices and output-file references are preserved. Images remain native MCP image blocks in content; their base64 data is not duplicated into structured results.
When an assistant opens a workspace via workspace_open, the bridge automatically discovers and inlines relevant project context (AGENTS.md, CLAUDE.md, etc.) and formats an <available_skills> catalog into the initial response. Assistants can query skill_info with a skill's name to view its complete prompt instructions, parameters, and frontmatter. Opening a workspace does not automatically execute project instructions or run arbitrary extensions.
cwd is fixed for the lifetime of a workspace. Relative paths resolve there; absolute paths, ~/, and ../ can read or modify other locations. Shell commands have the account's normal access, including existing noninteractive elevation. There is no directory allowlist or filesystem sandbox. A shell cd affects that command only. The server never changes its process-wide working directory.
Workspaces are in-memory directory records, with at most 64 open at once. The server reclaims the least recently used idle workspace when a new open request needs room, protecting any workspace with active commands. Workspaces survive HTTP reconnection and transport-session closure. They expire on explicit close, LRU reclamation, or server restart. A workspace ID is a routing handle, not a user or conversation identity. All authenticated clients share the same owner's access. Close unused workspaces; restarting the server clears them all.
HTTP protocol sessions are separate from workspaces. The server keeps at most 64, reclaiming the least recently used idle session when a new connection needs room. Active requests remain protected, including commands whose HTTP caller disconnected; an idle notification stream does not reserve a slot. Clients receiving HTTP 404 for an expired session must initialize again and can continue using their workspace IDs. If all sessions are busy, new connections receive HTTP 503 until a request finishes.
Read before editing. write and edit require the returned revision as expected_revision, or "missing" to create a file. Pi 0.85.1's edit input is edits: [{oldText, newText}], with all replacements matched against the original file.
Every write, edit, and bash requires a request_key, unique within its workspace. Retry an interrupted request with exactly the same arguments and key. The server returns its cached result, waits for the original call, or returns a durable receipt; it does not dispatch that key again. Reusing a key with different arguments returns REQUEST_KEY_CONFLICT. This still works with an expired workspace ID after closure or restart.
After a crash, an unfinished receipt reports OUTCOME_UNCERTAIN. Inspect the actual files or processes before deciding what to do next. A failed or cancelled command may already have produced effects. Changing the request key authorizes a new operation; it is not a safe automatic retry.
Receipts store metadata in a private SQLite database: tool, workspace, paths, revision, exit status, and output-file reference where available. They do not store command text, file contents, or conversations. The last 64 mutation results are cached in memory; after eviction/restart only the receipt remains. Keep the state directory to retain retry protection. Receipt metadata is retained until you maintain it locally.
File operations share path locks and use atomic replacement with revision checks. They preserve permission bits and follow symlink targets. Replacement creates a new inode, so ownership, ACLs, extended attributes, and hard-link relationships are not preserved. Arbitrary shell commands and external programs do not participate in these locks. The workspace is not protection against two conversations changing the same files. Use worktrees or coordinate changes when needed.
Commands default to a 120-second timeout, with a maximum of 3600 seconds. The client/tunnel may impose a shorter deadline. Shell stdin is closed; interactive prompts cannot be answered through bash. Pi bounds output and reports a temporary full-output file when truncated. read snapshots regular files up to 32 MiB; use a bounded command for larger files or special devices.
MCP cancellation and workspace closure abort the affected active calls. Graceful server shutdown aborts all active calls. None of these undo completed effects. A forced process kill or deliberately detached job can leave work running. For long jobs, use the OS's existing process supervisor and inspect/stop those jobs explicitly.
File locks live under the state directory. A forced crash during a write can leave a stale lock; inspect it and verify no writer remains before removing it. Locks never expire automatically while a writer may still be active.
npm run install:service -- --start
systemctl --user status rig-bridge.service
journalctl --user -u rig-bridge.service -n 50
systemctl --user stop rig-bridge.serviceWithout --start, the installer writes and validates the unit without enabling or starting it. --print prints the unit without installing it. It captures this checkout's absolute path, Node executable, and current PATH; rerun after moving the checkout or changing Node. The installer does not configure a tunnel or enable user lingering. Boot/login behavior follows the user's existing systemd configuration. Other platforms can launch the Node command with their preferred supervisor.
To connect ChatGPT to your local MCP tools using OpenAI's Secure MCP Tunnel (e.g. tunnel_your_id_here):
Set your tunnel runtime key (from OpenAI Platform > Tunnels) in .env or your shell:
cp .env.example .env
# Edit .env and set CONTROL_PLANE_API_KEY=...Run the tunnel (auto-downloads tunnel-client if not found):
npm run tunnelOr specify options:
npm run tunnel -- --tunnel-id tunnel_your_id_here --api-key <key>To run as a background service alongside rig-bridge.service in Linux / WSL systemd:
npm run install:tunnel-service -- --start
systemctl --user status rig-bridge-tunnel.servicenpm run check
npm run test:tunnel # Optional: requires tunnel-client 0.0.14 with dev proxyTests use real MCP clients and Pi implementations: project routing, unrestricted paths, image reads, edits/revisions, concurrent HTTP calls, cancellation, close/shutdown, authentication, restart receipts, and uncertain outcomes after a forced server crash. The optional test routes two clients through a real tunnel-client development proxy. It uses disposable local control infrastructure, not a deployed remote assistant connection.
Linux is the tested platform. Windows/macOS runtime behavior and an actual remote assistant round trip still require validation before claiming those environments are supported.
Run a real command on this workspace's computer using Pi, without another model. Full account access; sudo -n uses existing elevation. cd affects this command only. On timeout, cancellation, or lost connection inspect effects before retrying.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | ||
| timeout | No | ||
| request_key | Yes | Unique operation key within this workspace. Reuse only for the exact same request; uncertain outcomes must not be blindly retried. | |
| workspace_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this destructive and not read-only, but the description goes further by disclosing full account access, sudo -n behavior, per-command cd scoping, and the need to inspect effects before retrying after timeout/cancellation/disconnect. This materially improves the agent's risk assessment.
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?
Four short sentences, each carrying distinct operational value: execution semantics, privilege level, state scoping, and retry safety. There is no filler or repetition of schema fields.
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 high-risk arbitrary-execution tool with no output schema, the description covers privileges, side effects, and retry behavior well. It stops short of describing what the tool returns on success/failure, but the safety-critical information an agent needs before invoking is present.
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 only 25% (request_key), yet the description does not explain command, timeout, or workspace_id beyond naming 'command' in its first sentence and loosely referencing timeout. It does not compensate for the undocumented parameters with units, defaults, or relationships.
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 opens with a specific action and resource: 'Run a real command on this workspace's computer using Pi.' It also clarifies this is actual execution rather than delegation ('without another model') and full account access, which clearly separates bash from sibling read/write/edit 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 context is clear: use this tool when you need real shell execution, and the retry caution tells the agent what to do after interruptions. However, it does not explicitly state when to prefer sibling tools (read, write, grep) or mention exclusions, leaving selection guidance mostly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Precisely edit a file using Pi's real edit implementation. All oldText entries match the original file. Read first and provide expected_revision; returns the actual diff.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path or path relative to the workspace. Home is a starting directory, not a sandbox. | |
| edits | Yes | ||
| request_key | Yes | Unique operation key within this workspace. Reuse only for the exact same request; uncertain outcomes must not be blindly retried. | |
| workspace_id | Yes | ||
| expected_revision | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds value by explaining the edit is 'real' (not simulated), that oldText must match the original file, and that the tool returns the actual diff. It also implies the operation is not idempotent by requiring expected_revision. No contradiction with annotations.
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?
Three sentences, each earning its place: what the tool does, the matching constraint, and the required workflow plus return value. No fluff, no repetition of schema details.
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 destructive, non-idempotent edit tool with no output schema, the description covers the key operational facts: read first, provide expected_revision, oldText must match, returns the diff. It doesn't explain what happens on mismatch or how the diff is formatted, but the core workflow is complete enough for an agent to call it correctly.
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 40%, so the description must compensate. It does: it explains expected_revision ('provide expected_revision'), clarifies oldText semantics ('All oldText entries match the original file'), and mentions the return value ('returns the actual diff'). The request_key semantics are only in the schema, but the description's guidance covers the most critical parameter behavior.
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 a specific verb and resource: 'Precisely edit a file using Pi's real edit implementation.' It distinguishes itself from write (the sibling that creates/overwrites files) by emphasizing precise, oldText-matched edits. The phrase 'All oldText entries match the original file' clarifies the edit semantics.
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 gives clear usage guidance: 'Read first and provide expected_revision.' This tells the agent the prerequisite step and a required parameter. It doesn't explicitly name alternatives or when-not-to-use, but the sibling list (write, bash) and the edit-vs-write distinction are implied. The instruction to read first is concrete and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find files by glob using Pi. Use a bounded path to avoid scanning unrelated mounts.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Absolute path or path relative to the workspace. Home is a starting directory, not a sandbox. | |
| limit | No | ||
| pattern | Yes | ||
| workspace_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and non-destructive. The description adds meaningful behavioral context beyond that: it warns that find can scan across mounts, and the path schema note clarifies that home is a starting directory, not a sandbox. No contradiction with annotations.
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?
Two sentences with no filler: the first states the core purpose and the second gives a practical, front-loaded usage note. Every sentence earns its place.
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?
At moderate complexity with four parameters and no output schema, the description is too sparse. It does not explain the limit parameter, the meaning of workspace_id, return value format, or glob syntax expectations, so an agent may not call it correctly.
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 only 25%, so the description needs to compensate. It clarifies that pattern is a glob and advises bounding path, but limit and workspace_id are left undocumented in both the schema and the description, leaving required parameters underspecified.
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 opens with a specific verb and resource: 'Find files by glob'. The glob qualifier distinguishes this from sibling tools like ls and grep, although it doesn't name alternatives and the phrase 'using Pi' is ambiguous.
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 advice to 'Use a bounded path to avoid scanning unrelated mounts' is a concrete usage tip, and glob-based search implies when the tool is appropriate. However, there is no explicit guidance on when to choose find over related siblings such as ls or grep.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search file content using Pi and return matching lines.
| Name | Required | Description | Default |
|---|---|---|---|
| glob | No | ||
| path | No | Absolute path or path relative to the workspace. Home is a starting directory, not a sandbox. | |
| limit | No | ||
| context | No | ||
| literal | No | ||
| pattern | Yes | ||
| ignoreCase | No | ||
| workspace_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds little beyond that: it repeats the basic return behavior and introduces the unexplained 'Pi' engine. It does not disclose regex semantics, glob behavior, context/limit effects, or hidden-file handling, which would be useful for a grep-like tool.
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 short but incomplete in a way that undermines usability. The phrase 'using Pi' is vague and unexplained, so not every sentence earns its place. It is more underspecified than appropriately concise.
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 tool with 8 parameters)Skip the XML structure. The output should be wrapped in a single code block with language JSON. The description doesn't explain the return format beyond 'matching lines,' nor does it clarify pattern syntax or when to prefer this over find/read. The read-only annotation helps, but the overall package is too sparse for confident correct invocation.
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 only 13%, so the description must compensate for explaining the parameters, but it does not. The names pattern, glob, limit, context, literal, ignoreCase, and workspace_id are left to inference. The description is entirely about the operation, not the parameter meanings.
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 identifies the operation as a file-content search that returns matching lines, distinguishing it conceptually from siblings like ls or find. The phrase 'search file content' communicates the resource and action. However, 'using Pi' is unexplained jargon that weakens an otherwise clear 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?
There is no guidance on when to use grep versus find, read, or bash. The description does not mention alternatives, exclusions, or context such as 'use this to search file contents, not filenames.' Usage must be inferred entirely from the command-style name and sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List directory contents using Pi.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Absolute path or path relative to the workspace. Home is a starting directory, not a sandbox. | |
| limit | No | ||
| workspace_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds no behavior beyond the core listing action; that is adequate for a simple read-only tool.
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 short sentence with no fluff, though 'using Pi' is unnecessary and slightly vague. It is concise without being under-specified.
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 read-only listing tool, the combination of the safe annotations and clear core action is minimally sufficient. However, return behavior and the meaning of limit/workspace_id are left unexplained, and no distinction from sibling search tools is made.
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 only 33%; only the path parameter is partially documented. The description contributes minimal parameter meaning (path should be a directory) but says nothing about limit or workspace_id, failing to compensate for the low coverage.
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?
States a specific verb and resource: list directory contents. It is clear what the tool does, though 'using Pi' is vague and it does not differentiate from siblings like find or read.
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 when-to-use guidance or alternative routing is provided. Siblings such as find and grep could overlap for listing/searching, but the description offers no criteria for choosing ls over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read actual file content using Pi. Returns a file revision for subsequent edit/write preconditions. Use offset/limit for more context.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path or path relative to the workspace. Home is a starting directory, not a sandbox. | |
| limit | No | ||
| offset | No | ||
| workspace_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds meaningful behavior beyond that: it returns a file revision that serves as a precondition for subsequent edit/write operations. This is valuable context not captured in annotations. The 'use offset/limit for more context' note also hints at pagination behavior. No contradictions.
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?
Two concise sentences with no fluff. The core action ('Read actual file content') is front-loaded, followed by the key behavioral output (file revision) and parameter guidance. Every sentence earns its place.
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?
The tool is simple and the annotations cover safety. The description explains the primary use (read for edit/write) and mentions the return value (file revision). It does not detail error handling or non-existent files, but that is minor. For a low-complexity read tool with rich annotations, this is nearly complete. A 5 would require explicit handling of edge cases or more precise parameter semantics, but this is adequate.
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 low at 25% (only 'path' has a description). The description compensates partially by mentioning offset/limit for 'more context', giving them meaning. However, it does not explain workspace_id or the exact semantics of limit/offset (e.g., whether they refer to lines or bytes). Given the low coverage, the description should do more to clarify all parameters, but it at least addresses two of them.
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?
States a specific verb ('Read') and resource ('file content'), and immediately distinguishes from sibling tools like ls (listing) and grep (content search). It also clarifies that it returns a file revision, which is a distinct outcome. The purpose is unambiguous and differentiates it from the other 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 clearly implies the primary use case: reading file content before an edit or write, since it returns a revision for preconditions. It also advises using offset/limit for more context. However, it does not explicitly mention alternatives or when not to use this tool, though the context makes it clear this is the dedicated read operation among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect available Pi skills or get the full instructions and metadata for a specific skill.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name of the skill to inspect. Omit to list all available skills. | |
| workspace_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the dual-mode behavior (list vs. inspect specific skill) and mentions 'full instructions and metadata' as the return content, which is useful. However, it doesn't disclose details like whether the output is verbose, whether it requires an active workspace, or what happens if the skill name is invalid. With annotations covering the safety profile, a 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, well-structured sentence that front-loads the core action ('Inspect available Pi skills') and then states the alternative mode. Every word earns its place, and it's appropriately sized for the tool's complexity.
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 read-only inspection tool with two parameters and no output schema, the description is mostly complete. It covers the two modes of operation and the schema covers the 'name' parameter's behavior. The main gap is the undocumented 'workspace_id' parameter, which is required and could confuse an agent about its role. Since the tool is simple and annotations cover safety, this is a minor gap.
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 50%: the 'name' parameter is well-described ('Name of the skill to inspect. Omit to list all available skills.'), but 'workspace_id' has no description beyond its type. The tool description adds the context that the tool inspects 'Pi skills' and that omitting name lists all, which aligns with the schema. However, it doesn't explain what workspace_id means or how it relates to the skill lookup, so the description doesn't fully compensate for the undocumented 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 clearly states the tool's function: inspecting available Pi skills or retrieving full instructions and metadata for a specific skill. It uses a specific verb ('Inspect') and resource ('Pi skills'), and the dual-mode behavior (list all vs. get one) is explicit. It doesn't explicitly differentiate from siblings, but the sibling list contains general workspace tools (read, ls, find, grep) rather than skill-specific tools, so the purpose is distinct enough.
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 when to use the tool: when you need to see available skills or get details on a specific skill. The input schema reinforces this by saying 'Omit to list all available skills.' However, it doesn't explicitly state when NOT to use it or name alternatives (e.g., 'use read to view skill files directly'), so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close this workspace and cancel its active calls. Does not undo changes or stop separately supervised jobs. Repeating close is harmless.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, yet the description says the tool 'cancels active calls' and 'closes' the workspace, which are side-effecting operations. This directly contradicts the readOnlyHint annotation, making the behavioral information unreliable.
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?
Three short sentences that front-load the action, then give caveats and idempotency behavior. Every sentence earns its place with no filler or repetition.
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?
The description covers the main operation and some behavioral caveats, but the contradiction with readOnlyHint leaves the agent uncertain about actual side effects. It also omits what happens on success or whether any confirmation/return value is produced, which matters given there is no output schema.
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 description does not mention the workspace_id parameter at all, and schema description coverage is 0%. For a single self-explanatory parameter the schema provides the name and type, but the description adds no guidance on how to obtain or format the value.
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 a specific verb 'Close' with a clear resource 'workspace', and adds what the action involves ('cancel its active calls'). It is immediately distinguishable from the sibling workspace_open, which is the inverse operation.
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 closing the current workspace and notes what it does not do (undo changes, stop separately supervised jobs), but it never explicitly states when to use this tool versus alternatives like workspace_open. The guidance is limited to implied context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a local working directory and return a workspace_id, account, Git state, inlined project instructions, and available skills. Omit cwd for home. This is directory routing, not a sandbox; absolute and parent paths remain usable.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true and destructiveHint=false already communicate safety, and the description adds meaningful behavioral context: this is not a sandbox, and absolute and parent paths remain usable. It also discloses what the tool returns, going beyond the annotations. No contradiction with the annotations is present.
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?
Three dense, load-bearing sentences with no filler. The primary action and return values are front-loaded, the parameter default is stated compactly, and the sandbox clarification earns its place by forestalling a common misconception.
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 low complexity, one optional parameter, and no output schema, the description is nearly complete: it covers the parameter, the default, path behavior, and return contents. It could add error conditions or post-open expectations, but nothing required for a correct call is missing.
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 0%, so the description must explain cwd, and it does: it defines it as a local working directory, states the default behavior when omitted, and clarifies that absolute and parent paths remain usable. It does not go into relative-path details, but for a single optional parameter this is sufficient.
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 names a specific verb and resource ('Open a local working directory') and enumerates the concrete return payload (workspace_id, account, Git state, instructions, skills). The 'directory routing, not a sandbox' clarification further distinguishes it from container-like or command-execution 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?
It gives a clear usage rule ('Omit cwd for home') and states that this is directory routing, but it never explicitly says when to prefer this tool over siblings like read, ls, or workspace_close. The intended usage is implied rather than stated as a decision rule, and no alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or replace a file using Pi. expected_revision must be the last read revision, or 'missing' to create a new file. Returns its new revision.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path or path relative to the workspace. Home is a starting directory, not a sandbox. | |
| content | Yes | ||
| request_key | Yes | Unique operation key within this workspace. Reuse only for the exact same request; uncertain outcomes must not be blindly retried. | |
| workspace_id | Yes | ||
| expected_revision | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and non-read-only behavior. The description adds valuable behavioral context by explaining the concurrency contract around expected_revision and confirming that the tool returns the new revision. No contradiction with annotations.
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 two sentences with no filler. It front-loads the purpose and then gives the critical revision guidance and return value, earning every word.
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 file write tool, the description covers the core purpose, the key concurrency rule, and the return value. It does not discuss failure modes or parent-directory creation, but annotations and schema fill much of the safety context.
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 only 40%, and the description compensates for the most important undocumented parameter by explaining expected_revision semantics precisely. However, it adds little about other parameters like content or workspace_id beyond what their names and schema descriptions imply.
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 a specific verb and resource: 'Create or replace a file.' It clearly conveys the operation's scope. It does not explicitly differentiate from the sibling 'edit' tool, but 'create or replace' implies whole-file operations versus edits.
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 necessary practical guidance through the expected_revision requirement, telling the agent when to use 'missing' for new files or the last read revision for replacements. However, it does not explicitly state when to prefer write over edit or other alternatives, leaving this to inference.
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.
v0.1.2basheditfindgreplsreadskill_infoworkspace_closeworkspace_openwriteScored across 10 tools
Each tool has a clear, distinct purpose: workspace lifecycle, file listing/searching/reading, content modification, shell execution, and skill inspection are cleanly separated. Write vs. edit is explicitly differentiated by whole-file replacement versus precise text edits.
Most tools use simple lowercase command-style names like read, ls, grep, and write, which is consistent and readable. workspace_open, workspace_close, and skill_info are minor deviations from the bare-command pattern but remain predictable and intuitive.
Ten tools is a well-scoped count for a workspace/file/shell bridge. Each tool earns its place and the set covers the core operations without bloating the surface.
The toolset covers workspace open/close, file reading, listing, searching, writing, editing, shell execution, and skill inspection. Dedicated delete/move or workspace-list tools are absent, but bash and the workspace tools provide reasonable workarounds.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
