全局搜索接口

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

没有任何 annotations，描述承担全部行为披露责任。然而它只说明了匹配字段，未披露搜索是否大小写敏感、是否模糊匹配、返回结果的排序或分页行为、以及 limit 参数的作用。行为信息严重不足。

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?

描述只有一句话，直接说明工具用途和匹配范围，没有任何冗余。句子结构清晰，关键信息前置，符合简洁要求。

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?

对于仅有 2 个简单参数的搜索工具，描述给出了核心功能和匹配范围。但没有输出 schema，也未说明返回内容的具体形式，且未提及 limit 参数的行为。虽然基本可用，仍有明显信息缺口。

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 覆盖率为 100%，keyword 和 limit 均有明确描述和示例，因此 baseline 为 3。描述中没有额外补充参数语义，但也没有遗漏关键信息，schema 已足够。

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?

描述使用明确的动词「搜索」和资源「接口」，并具体说明匹配范围（接口名称、路由、分类名）。这与兄弟工具 list_apis（列出接口）、list_categories（分类）、get_api_doc（获取文档）能清晰区分，agent 不会被误导。

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?

描述隐含了使用场景：当用户需要按关键词查找接口时使用。但没有明确说明何时不使用，也未提及替代方案（例如浏览全部接口用 list_apis、按分类浏览用 list_categories）。缺乏明确的排除条件。

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