AI 小白学 Tool Calling 完全指南

一句话总结

Tool Calling = AI 决定"用什么工具+参数"，代码去执行，结果喂回给 AI 继续回答。

为什么需要 Tool Calling？

没有 Tool Calling 的 AI：

你：数据库现在有多少条笔记？
AI：抱歉，我不知道。（训练数据是截止的）

有 Tool Calling 的 AI：

你：数据库现在有多少条笔记？
AI：让我查一下 → 调用 get_dashboard_stats() → 拿到结果 → "当前有 9 条笔记"

核心流程图

你（问问题）
    ↓
① AI 收到问题 + 可用的工具清单
    ↓
② AI 决定用哪个工具 → 返回 tool_use（工具名 + 参数）
    ↓                          ← AI 只负责"决定"，不负责"执行"
③ 框架/代码 执行对应的函数 → 拿到结果
    ↓
④ 结果发回给 AI → AI 组织回答
    ↓
你（看到答案）

关键概念

1. Tool Definition（工具定义）

每个工具都需要一个描述，告诉 AI 这个工具是干什么的：

Python

get_dashboard_stats.tool_definition = {
    "name": "get_dashboard_stats",          # 工具名
    "description": "获取笔记中心统计信息",    # 什么时候用
    "parameters": {                          # 需要什么参数
        "dry_run": {
            "type": "boolean",
            "description": "True=只预览",
        }
    }
}

2. tool_use（AI 的返回）

AI 决定用工具时，API 返回的结构：

JSON

{
  "type": "tool_use",
  "name": "search_notes",
  "input": {"query": "Agent"}
}

3. tool_result（执行结果喂回给 AI）

JSON

{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "call_123",
    "content": "{"total_notes": 9}"
  }]
}

三个层次

层	谁写的	作用
系统提示词	Claude Code 团队	告诉 AI 有哪些工具可用
运行框架	Claude Code 团队	实现"收到 tool_use → 执行 → 结果发回"的循环
API 协议	Anthropic API 团队	定义 tool_use / tool_result 的数据格式

你只需要定义好工具函数 + tool_definition，剩下的循环机制框架自动处理。

亲手实践：在笔记中心写工具

你写的第一个工具：reorder_note_titles()

作用：把笔记标题里的序号按实际排列顺序重排。

Python

def reorder_note_titles(dry_run=True):
    # 1. 查出所有笔记（按显示顺序）
    # 2. 循环重编序号：位置1→"1."，位置2→"2."...
    # 3. dry_run=True 只预览，False 才真正修改

安全机制：默认只预览不修改（dry_run=True），确认后再执行。

完整的工具列表

在 note-center/tools.py 中定义了 7 个工具：

工具	作用
`get_recent_notes(limit)`	获取最近笔记
`search_notes(query)`	搜索笔记
`get_notes_by_tag(tag_name)`	按标签筛选
`get_note_by_id(note_id)`	获取笔记详情
`get_tag_statistics()`	标签统计
`get_dashboard_stats()`	总体统计
`reorder_note_titles(dry_run)`	重排标题序号

和已学概念的关系

Skill ── 别人配好的一组工具调用脚本
Agent ── 自动循环 Tool Calling（思考→调工具→拿结果→再思考）
MCP   ── 通过标准协议暴露工具给 AI
         ↑
    Tool Calling = 它们三个的发动机

记住这句话

AI 只负责"决策"，代码负责"执行"。