pi-web-mcp

pi-web 连接自检

piweb_status

Read-only

Check MCP-to-pi-web connection config—address, password source, session counts, and read/write boundaries—to troubleshoot connection failures.

Instructions

检查 MCP 到 pi-web 的连接配置是否正常：地址、密码来源、会话总数、运行中的会话、读写边界（是否只读、允许写入的项目根）。连不上时先用这个排查。

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "piweb_status"
  }
}

Input Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.1.0Oct 20, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds non-obvious value by enumerating the diagnostic fields returned (address, password source, session counts, read/write boundary and writable project roots). It does not describe output shape in detail, but with readOnly annotations and no output schema this is a solid disclosure.

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

Conciseness4/5

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

Front-loaded with the purpose, then a colon-delimited field list, then a short usage cue. Dense but every clause adds information; the field enumeration is slightly listy but earns its place by standing in for a missing output schema.

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

Completeness5/5

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

With no output schema and no parameters, the description must supply the return-value picture, and it does so by naming the diagnostics reported. An agent knows what a successful check yields and what it means for the read-only/writable-root boundary.

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

Parameters4/5

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

Zero parameters, so there is nothing to document; the baseline for a no-param tool applies. No misleading parameter claims are made.

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

Purpose5/5

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

States a specific verb+resource ("检查 MCP 到 pi-web 的连接配置") and enumerates exactly what is inspected: address, password source, session totals, running sessions, and read/write boundaries. No sibling tool performs a connection/config health check, so it is clearly distinguishable from the session/file/git tools.

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

Usage Guidelines4/5

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

Explicit trigger given: "连不上时先用这个排查" – use it first when the connection fails. Clear usage context, though it does not name which sibling to fall back to after the check passes or what a failed check implies for subsequent calls.

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