搜索鸿蒙开发者文档

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds valuable behavioral context: it returns matching text snippets and a document identifier 'parent', and mentions near-real-time synchronization with the official website. This goes beyond annotations by disclosing the return format and data freshness, though it doesn't detail pagination or limits.

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 description is concise and front-loaded: it states the core function first, then lists content types, then provides routing alternatives. Every sentence earns its place, with no filler or redundancy. It is well-structured for quick parsing.

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 tool is simple (one parameter, no output schema). Annotations cover read-only and open-world behavior. The description adds return format (snippets + parent identifier), how to get full text (harmonyos_get_docs), and when to use alternatives (Connect API). Nothing essential is missing for an agent to call it correctly.

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?

The schema has one parameter 'query' with a description that already explains it accepts Chinese or English search terms with examples. Schema coverage is 100%. The tool description adds no additional parameter-specific semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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 clearly states the tool searches HarmonyOS official documentation via Huawei's MCP, listing content categories (version notes, API reference, guides, etc.) and explicitly distinguishes it from siblings by naming harmonyos_get_docs for full text retrieval and agc_search_api/agc_get_api_doc for Connect API parameters. The verb '检索' (search) and resource 'HarmonyOS 官方文档' are specific and unambiguous.

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 provides explicit routing guidance: use harmonyos_get_docs when snippets are insufficient, and prefer agc_search_api/agc_get_api_doc for Connect API interface parameters. This tells the agent exactly when to choose this tool over alternatives, leaving no ambiguity.

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