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

Beyond the readOnlyHint=false annotation, the description discloses the important mutation semantics: the note overwrites any existing note, and an empty string clears it (a destructive side effect). It does not cover authorization needs or behavior when the word does not exist.

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 core action and the overwrite warning before the Args section. The Args block mirrors schema fields but each line adds meaning rather than restating titles.

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?

For a 2-parameter write tool with an output schema (so return values need no explanation) and a readOnlyHint annotation, this is largely sufficient. The remaining gap is the not-found / auto-create behavior for an unknown word.

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 0%, so the description carries the full burden and does: word is the literal idiom text (成语原文, not an ID) and note is the content, with the non-obvious edge case that an empty string clears the note. Minor gap: no length/format constraints on note.

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: write a free-text note on a given idiom, with example content types (易错点, 使用场景). It clearly is not a search/detail/status tool, so it is distinguishable from the sibling set, though no sibling is named explicitly.

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 usage context is implied by the example content types (mistake-prone points, usage scenarios), and the sibling list contains no competing note tool, so no alternatives need routing. However, there is no explicit when-to-use/when-not statement or prerequisite.

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

Does 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.

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

readOnlyHint=true is consistent with a lookup tool and the description adds the useful detail that progress metadata (draw count, status, notes) is bundled into the response. However, that return content is largely already captured by the output schema, and nothing is said about failure behavior for unknown idioms or about how notes/status are sourced.

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?

One front-loaded sentence states the tool's output scope, followed by a compact Args block. No filler, though the Args block partly restates the schema rather than adding new constraint detail.

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?

For a single-parameter read-only tool with an output schema and a readOnly annotation, the essentials are present. What's missing is the not-found behavior and the boundary against search_idiom, which an agent needs to route correctly among six siblings.

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 0% — the 'word' property carries only a title, no description — so the description must carry the parameter, and it does: '成语原文' plus a concrete example (守株待兔) tells the agent to pass the exact idiom form, not a keyword or partial string. A short note on whether variant/simplified forms are accepted would close the remaining gap.

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 names a specific verb (查/look up) and resource (an idiom's detail), then enumerates exactly what comes back: definition, origin, classical example sentences, and learning progress. That enumeration distinguishes it in substance from search_idiom and draw_idiom, though no sibling is named explicitly.

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: 'word: 成语原文' hints that this is for a single exact idiom rather than a fuzzy query, which is the natural split from search_idiom. But the description never states when to prefer this over search_idiom, nor what happens for a word that isn't in the collection.

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

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

readOnlyHint=true already declares this is a safe read, so the description's main added value is scope disclosure: a status breakdown and a hard cap of '最近抽的 10 个'. That fixed limit is genuinely useful behavioral context, but it stops short of describing ordering, totals, or what '有备注的' covers.

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?

A single compact sentence: purpose first, then a colon-led enumeration of the concrete metrics. No filler and nothing to trim.

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 no parameters, an output schema, and a readOnly annotation, the definition carries almost the entire burden of context already; the description's metric list is enough for an agent to call it correctly. It adds little on return shape, but the output schema covers that.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool is 4. The enumerated metrics give the agent a sense of what the argument-less call produces.

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 ('查看整体学习进度') and then enumerates exactly what the view contains: touch counts, per-status counts, noted items, and the 10 most recently drawn. The word '整体' (overall) implicitly separates it from the single-item sibling idiom_detail, though no sibling is named explicitly.

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: an agent can infer this is the aggregate dashboard to call before drilling into idiom_detail, but the description never says when to prefer it over that sibling or over search_idiom. No exclusions or prerequisites are stated.

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

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

Adds real value beyond the annotations by enumerating exactly what is destroyed (抽中次数、状态、备注) and what is preserved (词库本身); that is precisely the 'what gets destroyed' context the rubric credits. Gaps remain: irreversibility/undo, and behaviour when no record exists. Note the annotation pair itself is internally inconsistent (readOnlyHint=true alongside destructiveHint=true); the description agrees with destructiveHint, so the conflict appears to lie in the annotations rather than in the description.

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 main clause is front-loaded and the destructive scope is stated in the first sentence with zero preamble. The trailing Args block largely restates the schema and is the only mild 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?

With one parameter, an output schema, and annotations present, the description covers purpose, destroyed/preserved data, and the argument's meaning. It still omits whether the reset is reversible and what the tool does when the idiom has no learning record, which matter for a destructive operation.

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 0% (the only property has no description), so the description must carry the parameter, and it does add meaning with 成语原文 (the idiom string itself). It does not clarify matching rules — exact string vs fuzzy, case/whitespace, or what happens with an unknown word — leaving the 0%-coverage gap only partly closed.

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: 清空某个成语的学习记录, and immediately bounds the scope with 词库本身不受影响, which separates it from the word-bank-level siblings (search_idiom, draw_idiom). It does not name the near-neighbour it is distinguished from (update_status, add_note), so an agent must infer the granular-vs-wholesale split.

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?

Use is only implied: clearing a whole learning record suggests use when an idiom should be re-learned from scratch, versus the granular siblings update_status and add_note. No explicit when-to-use/when-not, no prerequisites (e.g. must the record already exist), and no alternatives are named.

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

Does 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.

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

The annotation readOnlyHint=false already marks this as a write. The description adds meaningful context: judging is delegated to the model and the server does not score, which sets expectations for the write. However, it does not state whether an existing record is overwritten, what happens if the idiom is unknown, or whether the update is one-way.

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 main sentence comes first and is followed by the Args block; every line adds information that is used at call time. The status definitions are dense but justified, since they replace a missing enum.

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?

An output schema exists, so return values need not be described, and the annotation covers write semantics. Even so, for a mutation tool with 0% schema coverage, the definition omits whether the 'word' must already exist, and whether repeated calls update or append. These gaps are minor but real.

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 has to carry the parameters, and it does this well for 'status': three named values (learning/reviewing/mastered) with concrete decision criteria that are not encoded as a schema enum. By contrast, 'word' gets only '成语原文', with no detail on whether it must be the exact canonical form or must already exist.

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: '更新成语的掌握状态' (update an idiom's mastery status), scoped to the user's demonstrated performance in the conversation. This clearly distinguishes it from the siblings 'progress' (which reads) and 'reset_word' (which clears), so an agent can tell what this tool does without opening the schema.

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?

'由 AI 自行判断调用，服务端不做判分' explicitly tells the agent that it is the one deciding when to call, and that no server-side grading happens. That resolves the main ambiguity for a judgement-writing tool. It does not name the alternative actions (implicitly reading status via 'progress', or clearing status via 'reset_word'), so the routing is implied rather than spelled out.

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