MCP 工具声明格式

MCP 工具声明就是服务器向模型交代「我有哪些工具、每个工具要什么参数」的那段结构化描述，核心三件套是 name、description、inputSchema。模型靠它判断该不该调，以及参数怎么填。

用法：在 MCP 服务器里给每个工具写一份声明。name 用动词开头的唯一短名；description 说清干什么、什么时候用；inputSchema 用 JSON Schema 写参数类型、必填项和可选值。客户端通过 tools/list 取到声明交给模型，模型决定调用后走 tools/call 把参数传回来。

一个最小的工具声明：

{
  "name": "read_file",
  "description": "读取指定路径的文本文件内容，用户要看某个文件时使用",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "文件的绝对路径" }
    },
    "required": ["path"]
  }
}

在服务器代码里注册时，用装饰器加类型注解即可，SDK 会按函数签名自动生成上面的 inputSchema：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("demo")

@mcp.tool()
def read_file(path: str) -> str:
    """读取指定路径的文本文件内容"""
    with open(path, "r", encoding="utf-8") as f:
        return f.read()

mcp.run()

踩坑有两个。一是 description 写得含糊，比如只写「文件工具」，模型压根不知道该在什么场景调用，声明等于白写；二是 inputSchema 里漏了 required 或参数名和函数签名对不上，模型按声明传参过去直接报参数错误。声明和实际处理函数的参数必须一个字不差。