Randomly draw Chinese idioms for study, prioritizing unseen, least-drawn, and longest-unseen items while skipping recent and mastered entries by default; draw 1–10 and optionally include mastered.
随机抽成语学习。优先抽没抽过的；都抽过一轮后，抽得最少且最久没抽的优先。默认跳过最近 20 条和已掌握的。
Args: count: 抽几个（1~10） include_mastered: 是否把已掌握的也放回抽奖池
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| include_mastered | No |
| 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?
readOnlyHint=false matches the description, which implies the draw records into the draw history (that's what makes 'never drawn' and 'stalest' meaningful). The prioritization rules and default exclusions are real behavioral context beyond the annotation, though the persistence side effect could be stated outright.
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?
Front-loaded with the purpose, then the algorithm, then parameter notes — every sentence carries information. The separate Args block is slightly redundant with the schema but not wasteful.
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?
With an output schema present, return values need not be described, and both parameters are documented. The one remaining gap is whether the draw is recorded/persisted and what happens when the pool is exhausted.
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 carry the load and does: it gives count a range (1~10) that the schema lacks, and explains include_mastered as putting mastered items back into the pool. Only edge behavior (e.g. out-of-range count) is unaddressed.
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?
States a specific verb+resource: randomly draw idioms for study, with an explicit selection algorithm. Clear enough to distinguish from search_idiom or idiom_detail, though it never names those siblings to sharpen the distinction.
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?
Explains the selection policy (prefer never-drawn, then least-drawn and stalest) and the defaults (skip the most recent 20 and mastered items). No explicit when-not guidance or sibling routing, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.