[Bug]: 只读平台工具的描述写 "Query: projectId",但 schema 要求包进 query 对象,首次调用必然失败

Open Beginner friendly
#1,084 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
76/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
go
Domain
api, backend, devtools

Research direction

Start with the tool descriptions in internal/application/operations.go and how they are assembled in internal/httpapi/agent_tool_catalog.go; compare these with the input schema in internal/mcpserver/schema.go. Check how existing prompts describe the query, path, and body wrappers. Done means a first call using the documented parameter shape passes validation for read-only tools.

Written by the indexing model from the issue text.

Description

[Bug]: 只读平台工具的描述写 "Query: projectId",但 schema 要求包进 query 对象,首次调用必然失败

Component / host: Platform — web / API
Edition: Platform
LoopForge version: v0.4.0(自托管镜像,诊断中平台版本显示为 (devel))

What happened?

模型第一次调用任何只读平台工具(agentflow__*)时,必然先吃一次参数校验失败,第二次才成功。

实测片段(已脱敏):

tool: mcp__agentflow_session__agentflow__workflows_list
status: failed
Validation failed for tool "mcp__agentflow_session__agentflow__workflows_list":
  - projectId: unknown field
Received arguments:
{ "projectId": "welcome" }

同一次调用把参数改为 {"query": {"projectId": "..."}} 后立即成功。另一个工具同样现象:

tool: mcp__agentflow_session__workbench_tool_schema
  - name: missing
  - tool: unknown field
Received arguments:
{ "tool": "issues_save" }

原因链(代码定位)

  1. internal/application/operations.go:81 这条只读操作的自述是:

    List SOP workflow definitions. Query: projectId (that project's SOPs plus generic templates),
    q (match id/name/description). Always pass projectId when a project is known.
    

    这句话在语义上明确要求"传 projectId",但没有说明要放在 query 里。

  2. internal/httpapi/agent_tool_catalog.go:361-376 把描述拼成
    op.Description + " (" + op.Method + " " + op.Path + ")" 直接交给模型,
    没有附加任何"参数需包在 query 对象内"的说明。

  3. internal/mcpserver/schema.go:48-90 生成的 inputSchema 顶层是
    {"type": "object", "additionalProperties": false},属性只有 path / query / body。
    因此顶层出现 projectId 一定被判 unknown field。

  4. 全仓库检索 body/path/query 这组包装说明,只出现在写入草稿路径:

    • internal/httpapi/assistant.go:1059("提交草稿前……按 body/path/query 包装参数")
    • internal/httpapi/agent_tool_terminal.go:76

    直接调用的只读工具没有任何等价提示。

也就是说:工具描述本身把模型引向了错误形状,而唯一正确的包装规则只写在另一条链路(写草稿)的提示里。模型不可能从只读工具的描述里推断出这层包装。

影响

  • 每个只读工具在模型首次使用时都要浪费一轮调用,并成功前先在界面上留下一条"执行失败"。
  • 一次实测对话里 13.4 秒内出现 12 次工具失败,其中 2 次属于这一类;叠加模型自身写脚本的错误后,用户看到的是连续红字,观感是"平台坏了",而这些错误其实都是可避免的契约模糊。
  • 这类错误对用户没有信息量:unknown field 不告诉模型"应该放在 query 里",只能靠试错。

期望行为

任选其一即可显著改善:

  1. 在只读工具描述里直接写出包装形状,例如
    query: {projectId?: string, q?: string},或在描述末尾统一加一句
    "所有参数放入 query 对象,不要把参数放在顶层"。
  2. 在 platformToolInputSchema 生成描述时,把 query / path / body 的可用字段展平进描述。
  3. 校验失败时返回可执行的纠正建议(例如
    unknown field "projectId"; put it under "query"),而不是只回 unknown field。

Reproduction

  1. 部署平台 v0.4.0,在 AI 对话中配置一个可用的自定义运行时与模型。
  2. 在对话里问"当前项目有哪些 SOP"。
  3. 观察模型第一次调用 agentflow__workflows_list 时带 {"projectId": "..."} 并报
    projectId: unknown field。
  4. 模型改为 {"query": {"projectId": "..."}} 后成功。

Sanitized diagnostics

{
  "kind": "tool.failed",
  "source": "cli",
  "tool": "mcp__agentflow_session__agentflow__workflows_list",
  "message": "Validation failed for tool \"mcp__agentflow_session__agentflow__workflows_list\":\n  - projectId: unknown field\n\nReceived arguments:\n{\n  \"projectId\": \"welcome\"\n}"
}
{
  "kind": "tool.failed",
  "source": "cli",
  "tool": "mcp__agentflow_session__workbench_tool_schema",
  "message": "Validation failed for tool \"mcp__agentflow_session__workbench_tool_schema\":\n  - name: missing\n  - tool: unknown field\n\nReceived arguments:\n{\n  \"tool\": \"issues_save\"\n}"
}

Safety checks

  • 已移除凭证、私有端点、内部标识与个人数据。
  • 已检索现有 issue,未发现重复。
Dominant language
Go
Stars
711
Forks
114
Avg merge
15h
Merged PRs (30d)
134

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Tencent/LoopForge

All issues in Tencent/LoopForge

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.