search_docs

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

No annotations are present, so the description carries the full burden — and it delivers: it discloses query tokenization, ranking by number of matched keywords, OR-style matching (at least one keyword), matched fields, and the absence of full content in results. This goes well beyond a minimal 'search docs' statement.

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?

Two dense sentences cover purpose, query semantics, ranking, matching scope, result limitations, and the get_doc alternative. There is no filler, and the most decision-relevant behavior is front-loaded.

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?

The description covers the core behavior, ranking, matched fields, result brevity, and the flag to get_doc for full content. It is slightly less complete regarding list_docs as an alternative and the exact shape of returned result items, but these are minor for a search tool with fully described parameters.

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 coverage is 100%, so the baseline is 3. The description adds substantial value beyond the schema by explaining how the query parameter is interpreted (split by whitespace, ranked by matched keyword count) and what the query can match (title/summary/preview/category/id/path).

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?

The description states a specific action ('检索关键词') and a specific resource ('Neo-MoFox 官方文档'), then explains exactly what is matched and how results are ranked. It also differentiates itself from get_doc by explicitly noting that it returns excerpts rather than full content.

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 description gives clear context: use this to search docs, and if full text is needed, use get_doc. It does not explicitly mention when to choose list_docs over this tool, but the search-vs-listing distinction is reasonably inferable from the context.

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