Search Chinese idioms by keyword across idiom text, pinyin, or definition, and return matching entries with their draw counts. Use it to find relevant chengyu and see how often each has been drawn.
按关键词搜成语（匹配成语、拼音或释义），并附各自的抽中次数。
Args: keyword: 关键词，中文或拼音缩写（如 szdt） limit: 最多返回几条（1~20）
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| keyword | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already establishes that this is a safe read operation, so the description carries a lower burden. The description does add that each result includes its draw count ('抽中次数'), which is meaningful output context. However, it says nothing about match ordering, case sensitivity, or behavior when the keyword matches nothing. With annotations covering safety, a 3 is appropriate.
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 definition is front-loaded: the purpose sentence comes first, followed by a tight Args block. Nothing is redundant. It is terse without being cryptic, though the Args formatting is slightly more verbose than needed for two parameters.
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?
There is an output schema, so the description need not explain return values; the safety profile is covered by annotations; and both parameters are documented in the description, including a range the schema lacks. The remaining gap is the lack of guidance on related tools and on empty-result behavior, which is minor for this simple search tool.
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 compensate, and it does. It explains that the keyword can be Chinese or a pinyin abbreviation (example 'szdt') and that limit is a maximum with a 1–20 range. That range constraint is absent from the schema, which only shows the default. This is a substantial addition beyond the structured fields.
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 verb and resource: it searches idioms by keyword, matching against the idiom text, pinyin, or definition, and returns each result's draw count. This is clearly distinguishable from the sibling operations draw_idiom and idiom_detail, though it never names them explicitly. It is clear but lacks the explicit sibling routing that would earn a 5.
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?
Usage is only implied: the agent can infer it should search when it has a keyword phrase or pinyin abbreviation. There is no explicit guidance on when to prefer this over idiom_detail or draw_idiom, and no mention of what to do when there are no matches. It is adequate but has a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.