astrbot-mcp

kb_learn_file

Ingest a local text file into a searchable knowledge base. Specify a sandboxed file path and optional comma-separated tags to organize learned content.

Instructions

从本地文本文件学习内容并写入知识库。

Args: path: 相对于 files.root 沙箱的文件路径。 tags: 逗号分隔的标签。

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>"
    },
    "name": "kb_learn_file"
  }
}

Input Schema

Name	Required	Description	Default
`path`	Yes
`tags`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 29, 2026

TDQS

B3.1/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden. It states that content is written into the KB and that the path is sandboxed under files.root, but says nothing about chunking, deduplication, whether an existing entry with the same content is overwritten, or any size/rate limits — important for an idempotency-sensitive write tool.

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?

One summary sentence followed by a compact Args block — no waste and the purpose is front-loaded. The docstring formatting is a bit raw but does not impede comprehension.

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

Completeness3/5

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

An output schema exists, so return values need not be described. Still missing are the ingestion semantics (chunking, duplicate handling, size limits) and any error behavior for paths outside the sandbox, which leaves the agent with gaps for a knowledge-base write operation.

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?

Schema description coverage is 0%, so the description must compensate — and it does: `path` is clarified as being relative to the files.root sandbox, and `tags` is clarified as a comma-separated string with a default. Both parameters gain meaning beyond the bare schema titles, though the tags' effect on retrieval is not explained.

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

Purpose4/5

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

States a specific verb+resource: read a local text file and write its content into the knowledge base. The phrase '从本地文本文件' implicitly distinguishes it from kb_learn_url (URL ingestion), but no sibling is named explicitly, so an agent must infer the boundary.

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

Usage Guidelines2/5

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

There is no guidance on when to choose this over kb_add, kb_remember, or kb_learn_url, nor any prerequisite such as the file needing to exist inside the sandbox. The only hint is the word '本地' in the first sentence.

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