ask_kb

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

No annotations are provided, so the description carries the full burden, and it is notably forthcoming: it discloses the retrieve-to-generation pipeline, retrieval scoping by (client, project) with doc/web memory shared, an emitted ask access-audit, client auto-detection from clientInfo, and the exact shape of the LLM-unavailable error response. These are concrete behavioral traits beyond a basic read, especially the audit side effect and error contract.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded and the content is logically segmented into pipeline, v2 behavior, client semantics, and error handling. However, the entire description is duplicated in Chinese and English, which roughly doubles the length without adding information.

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

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

Given no output schema and sparse input schema, the description covers the important operational details: return shape (answer and sources), memory scoping, the audit side effect, and LLM-unavailable error handling. It does not specify the exact structure of sources or how the current (client, project) is fully resolved, but these are minor relative to what is disclosed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must add parameter meaning, and it does so only partially. It clearly explains client (optional, auto-detected from clientInfo) and indirectly ties project to memory isolation, but it does not define project's role directly nor describe the expected form/content of the required question parameter.

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

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

States a concrete action and resource: 'Knowledge-base RAG Q&A' / '基于知识库的 RAG 问答', with a described pipeline and return values (answer and sources). It is far from a tautology, but it does not explicitly contrast itself with sibling tools such as search_memory or read_memory.

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

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

The phrase 'Knowledge-base RAG Q&A' and the memory-isolation note imply use for natural-language questions grounded in the KB rather than for memory CRUD or document ingestion. However, the description offers no explicit when-to-use, when-not-to-use, or alternative-tool guidance, so an agent must infer the decision.

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