diana_knowledge_search

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses real behavior: Chinese queries are translated with DianaIE's official GUI glossary and the English sources searched with the translation ("shown as searched_in_english"), results are merged by rank with experiences first, and 已验证/未验证 labelling is explained. Mild tension worth noting: it lists a "community" source while annotations set openWorldHint=false, which suggests a possible remote corpus.

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?

It is front-loaded with the purpose, then language handling, then follow-up routing, then Args — a sensible order readable top-down. Slightly long, and a few details (the 已验证/未验证 gloss, the sibling list) could be trimmed, but each clause carries real information for an agent.

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?

For a four-parameter search tool with an output schema already defining return values, the description covers the query languages, source restriction, obsolete filtering, ranking order and the feedback loop. Nothing an agent needs in order to call it correctly and interpret the response is missing.

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%, yet the inline Args block documents all four parameters: query with worked examples in both languages ("受压断裂能怎么取值", "LB40/0053", "LINPAG"), sources with the enumerable values named, limit as result count, and include_obsolete as "also return experiences marked obsolete" — a semantic the bare boolean does not convey.

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?

"Search everything known about DIANA at once" gives a specific verb and scope, then enumerates exactly what corpus is covered: the experience handbook, the user's manual, shipped tutorials and verification examples, data-model keywords and script commands. This makes it clearly distinguishable from narrower siblings such as diana_manual_search, diana_api_search and diana_keywords.

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?

It gives concrete next-step routing ("Read more with diana_experience_list(id=...), diana_manual_read(page=...), diana_keywords(keyword) or diana_api_doc(name)") and a closing loop ("When a result solved the problem, call diana_knowledge_feedback"). What it does not state explicitly is when to prefer the narrow single-source search siblings over this broad one — an agent has to infer that this tool is the broad first pass.

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