FastMCP项目中如何为工具参数添加描述信息

在FastMCP项目中，开发者经常需要为工具函数的参数添加描述性信息，以增强API文档的可读性和易用性。本文将详细介绍如何利用Python的类型注解和Pydantic库来实现这一功能。

参数描述的实现方式

FastMCP基于Python的类型系统，结合Pydantic的Field类，为工具参数添加描述信息。具体实现方法如下：

from typing import Annotated
from pydantic import Field

@mcp.tool()
def add(a: Annotated[int, Field(description="第一个加数，必须是整数")], 
       b: Annotated[int, Field(description="第二个加数，必须是整数")]) -> int:
    """两数相加"""
    return a + b

这种写法利用了Python 3.9+引入的Annotated类型，结合Pydantic的Field类来为参数添加元数据。描述信息会被自动包含在生成的JSON Schema中。

生成的JSON Schema结构

当使用上述方法定义工具后，FastMCP会生成包含参数描述的JSON Schema：

{
  "tools": [
    {
      "name": "add",
      "description": "两数相加",
      "inputSchema": {
        "type": "object",
        "properties": {
          "a": {
            "description": "第一个加数，必须是整数",
            "title": "A",
            "type": "integer"
          },
          "b": {
            "description": "第二个加数，必须是整数",
            "title": "B",
            "type": "integer"
          }
        },
        "required": ["a", "b"],
        "title": "addArguments"
      }
    }
  ]
}

关于自动生成的标题字段

在生成的Schema中，FastMCP会自动为每个参数添加title字段，其值为参数名的大写形式。这是FastMCP的默认行为，目的是提供更友好的展示名称。目前版本中，这个特性是内置的，暂时没有提供关闭选项。

addArguments这个顶级标题也是自动生成的，它代表了整个输入参数的集合。这些自动生成的标题字段虽然不能直接关闭，但不会影响实际的功能使用。

最佳实践建议

1. 保持描述简洁明了：参数描述应该简明扼要地说明参数的用途和限制条件

2. 一致性原则：为所有重要参数都添加描述，保持API文档的完整性

3. 类型与描述结合：除了描述外，确保类型注解准确，如int、str等

4. 考虑国际化：如果面向多语言用户，可以在描述中使用简单英文或考虑后续支持多语言描述

通过这种方式，FastMCP开发者可以创建出具有丰富文档信息的API工具，大大提升API的可用性和开发者体验。