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

With no annotations, the description carries full transparency burden and delivers useful context: delta range, 14-day half-life decay, and assurance that FSRS is not tampered with or reviews faked. It does not cover edge cases like invalid numbers, but the provided behavior is substantive.

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?

Three sentences, front-loaded with the trigger condition, and every sentence serves a purpose: usage, parameter meaning, or alternative. No wasted words.

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?

Given the low complexity and presence of an output schema, the description covers the core behavior and usage context well. Missing details on idempotency_key usage and edge cases are minor but would strengthen completeness.

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. It explains delta's range and meaning, but the other three parameters (number, reason, idempotency_key) are left undefined beyond their names. This leaves a clear gap in parameter understanding.

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 adjusts priority of a numbered problem, with the trigger condition '仅在用户明确要求提高或降低某编号优先级时调用'. It explicitly distinguishes itself from sibling record_review, making the purpose 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?

Provides explicit when-to-use guidance ('only when user explicitly requests priority change') and names the alternative tool record_review for the case where the user reports a mistake. This is clear usage differentiation.

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?

With no annotations, the description carries full burden. It discloses immutable numbering, FSRS initialization, and safe retry via idempotency key, which are meaningful behavioral traits. It also cautions against unconfirmed writes. It does not cover duplicate_policy semantics or auth, but overall it adds valuable context beyond a bare create operation.

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?

Three sentences with no redundancy. It front-loads the core action and adds warnings and retry context efficiently. Every sentence earns its place.

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 description covers key aspects: saving confirmed data, immutable ID, FSRS initialization, and safe retry. The output schema exists, so return values need no explanation. It omits duplicate_policy semantics, but the schema's enum and default provide some guidance. Overall, it is complete enough for a create tool with a well-defined schema.

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 must compensate. It explains idempotency_key's role (safe retry) but provides no additional meaning for draft or duplicate_policy. The draft structure is self-evident from the schema, but the description adds little beyond that, leaving a significant gap for two of three parameters.

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 saves a confirmed, transcribed single question, assigns an immutable number, and initializes FSRS. This specific verb+resource combination distinguishes it from siblings like update_problem and search_problems.

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?

It explicitly warns not to write unconfirmed OCR guesses, providing a clear when-not-to-use condition. It also implies use for confirmed data and mentions idempotency for safe retries. However, it does not name alternative tools or discuss scenario-based selection.

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?

There are no annotations, so the description carries the burden of behavioral disclosure. It usefully reveals that it freezes the current version of selected questions and does not update FSRS. However, it omits other relevant behaviors such as whether it is asynchronous, whether it mutates problem records, or how the returned object relates to the export workflow.

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 only two sentences, front-loaded with the primary purpose and followed by a concise mode-specific detail and side-effect note. Every sentence earns its place with no filler.

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 description covers the core purpose and an important non-mutating behavior, and an output schema exists to document return values. However, given the nested request parameters, lack of annotations, and sibling export/status tools, it does not fully contextualize how this tool fits into the export lifecycle or whether the PDF generation is synchronous.

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. It adds meaning for the `scheduled` mode and `horizon_days`, which is helpful. But it leaves several parameters like `numbers`, `tags`, `subjects`, `max_questions`, and `idempotency_key` unexplained, and the `all_active` and `numbers` modes are not clarified.

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's specific action: freezing the current versions of selected problems and generating an A4 review PDF containing only the questions. It also describes the scheduled mode's selection criteria, distinguishing this creation-focused tool from the sibling read/update/export tools.

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 implies usage by explaining what scheduled mode selects and noting that generating the sheet does not update FSRS, which hints at a boundary. However, it never explicitly says when to use this tool versus alternatives, nor does it name sibling tools like record_review or mention when not to use this tool.

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?

With no annotations provided, the description carries the full burden. It clearly discloses what is affected ('指定导出及其 PDF 文件') and what is not ('题目、FSRS 或优先级'). This goes beyond the tool name and provides useful context about side effects. However, it does not mention permanence or irreversibility, which is a common expectation for a delete operation, but the deletion is inherently destructive and the scope is well specified.

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 a single sentence that is concise and front-loaded. It states the primary action, the target, and a clear exclusion of unintended effects. Every part earns its place, with no filler or unnecessary 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?

The tool is simple (one parameter, no annotations) and an output schema exists, so the description doesn't need to cover return values. However, the description lacks parameter guidance and explicit usage conditions. It covers purpose and side effects adequately, but the 0% parameter coverage creates a gap that the description does not fully fill, making it only minimally complete overall.

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 input schema has one parameter `export_id` with no description, and the schema description coverage is 0%. The description only references '指定导出' (specified export) without explaining the format of `export_id`, how to obtain it, or any constraints. Since the schema provides no information and the description barely adds value, the parameter semantics are weak.

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 explicitly states the tool's function: '删除指定导出及其 PDF 文件' (deletes the specified export and its PDF file). It specifies a clear verb ('delete') and resource ('export/PDF'), and the negative clause '但不会修改题目、FSRS 或优先级' distinguishes it from sibling tools that modify problems or priorities. This makes the purpose unambiguous and distinguished from siblings.

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 implies usage: use this when you want to remove an export and its PDF. The negative statement about not modifying problems/FSRS/priorities provides some guidance on non-use cases, but it does not explicitly name alternative tools or state 'when not to use'. Guidance is implied rather than explicit.

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?

With no annotations, the description carries the burden but does disclose the return fields, which is useful. However, it does not elaborate on error behavior, prerequisites, or whether it is a read-only operation.

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 concise sentence that effectively communicates the tool's purpose and key output fields.

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?

Given the tool's low complexity (one parameter) and the presence of an output schema, the description provides sufficient context about what the tool does and what information it returns.

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% and the description only restates that export_id is used as the key. It does not provide additional context such as where to find the export_id or any format constraints.

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's function: retrieving export status and associated metadata (file path, resource URI, size, SHA-256) using an export_id. This distinguishes it from sibling tools like list_exports and delete_export.

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?

No guidance is provided on when to use this tool versus alternatives. The description only states the action, not the context or exclusions.

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?

No annotations are provided, so the description carries the full burden. It implies a read-only operation by stating it returns data, and it specifies the exact metrics computed, which adds some behavioral context. However, it does not explicitly confirm non-modification, real-time vs. cached data, or any prerequisites, so it falls short of full transparency.

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 a single, tightly constructed sentence that front-loads the verb and lists all returned categories without redundancy. Every phrase earns its place, and it is easy to scan.

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?

Given the absence of parameters and the presence of an output schema, the description sufficiently conveys the tool's scope and return values. It could be more explicit that statistics cover the entire mistake book, but the listed categories and subject distribution provide a solid understanding.

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 has zero parameters, and the schema coverage is trivially 100%. With no parameters to describe, the baseline is 4. The description correctly adds no parameter details since none are needed.

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 uses a specific verb '返回' (returns) and clearly enumerates the exact statistics provided: counts for active, mastered, archived, currently due, and due within seven days, plus subject distribution. This distinguishes it from sibling tools that manage individual problems or exports.

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 offers no guidance on when to use this tool versus alternatives, nor does it mention any exclusions or alternative tools. Users must infer from the tool name and the nature of the stats that this is for aggregate overviews.

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?

With no annotations, the description carries the transparency burden. It clearly indicates a read operation ('读取') which implies no mutation, and it discloses the optional behavior of including complete review history. It does not explicitly state 'no side effects' or mention permission/rate limits, but for a simple get tool, the description provides sufficient behavioral context without contradiction.

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 one compact sentence with two clauses. The main function is front-loaded, and the optional feature is appended concisely. Every phrase earns its place; there is no fluff or repetition.

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 simple retrieval tool with two parameters and an output schema (which covers return details), the description is adequate. It covers the primary action and the only significant optional behavior (history). It does not detail error cases or prerequisites, but these are not critical for a get operation. Sibling tool names provide additional context that this is the single-problem fetch, not a search.

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 0% description coverage, so the description must compensate. It does so effectively: '固定编号' clarifies that 'number' is a fixed identifier, and '需要分析学习轨迹时可包含完整复习历史' explains the purpose and semantics of 'include_history'. Both parameters receive meaningful context beyond their type/default values.

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 uses a specific verb '读取' (read) with a clear resource '错题' (wrong problem) and method '按固定编号' (by fixed number). It distinguishes itself from sibling tools like search_problems by emphasizing precise retrieval via a fixed identifier, and it adds the optional history inclusion, making the purpose 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 usage context is implied: use this tool when you have a fixed number and need a precise read. It does not explicitly name alternatives or exclusion criteria (e.g., 'use search_problems if you don't know the number'), but the phrasing '按固定编号' signals the precondition. The history clause gives a specific trigger for including history, providing some situational guidance.

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?

With no annotations, the description carries the transparency burden. It explicitly discloses a key behavioral trait: it does not change scheduling state. It also indicates the output includes existence status. However, it does not mention other potential behaviors such as pagination or performance implications.

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 a single, concise sentence that front-loads the main purpose and adds a useful non-mutation caveat. There is no unnecessary filler or repetition.

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, but the description leaves gaps: no usage alternatives, no parameter semantics, and only partial return information. The output schema (if present) may cover return details, but the description alone does not make the tool fully self-explanatory.

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 provides limit and offset parameters with defaults but no descriptions (0% coverage). The description does not mention pagination or explain how these parameters affect results, leaving the agent to rely on parameter names alone. This is a clear gap for a list operation.

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 lists historical export files and their existence status, using a specific verb (list) and resource (exports). It is distinct from sibling delete_export and get_export_status in being a plural list, though it does not explicitly name alternatives. The title is broader but the description is precise.

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?

No explicit guidance on when to use this tool versus alternatives is provided. The non-mutation caveat hints at safe usage, but the description does not mention cases where other tools like get_export_status or delete_export would be more appropriate.

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?

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that the tool mutates FSRS scheduling and that 'skipped' does not modify the schedule. However, it omits other behavioral traits such as idempotency handling, required-field dependencies, or error conditions.

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 a single sentence that packs the core action, outcome semantics, and a usage note without redundancy. It is front-loaded with the primary purpose and uses efficient enumeration.

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 has 7 parameters, no schema descriptions, and an output schema, so the description needs to cover the essentials for correct invocation. It only addresses the 'outcome' enum and skipped behavior, leaving the remaining six parameters completely unaddressed. This is insufficient for a tool of this complexity.

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 by explaining parameters. It thoroughly defines the 'outcome' enum values, but does not explain the purpose or format of other parameters like 'number', 'idempotency_key', 'reviewed_at', 'duration_seconds', 'response_markdown', or 'notes'. This leaves most parameters underspecified.

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's verb and resource: '追加一次真实复习结果并更新 FSRS' (append a real review result and update FSRS). This distinguishes it from sibling tools that handle problems, review sheets, exports, or status changes.

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?

It provides explicit guidance on when to use certain outcome values, e.g., '普通答对应使用 correct，不要自动判为 easy' and explains that 'skipped' only records without altering scheduling. However, it does not explicitly mention when not to use this tool or compare it to alternatives, though the purpose is unique among siblings.

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?

With no annotations, the description carries the full burden for behavioral disclosure. It adds useful context about default sorting and that the response includes scoring components and reasons, which is non-obvious. However, it does not disclose potential side effects (e.g., read-only nature), pagination behavior, or any limitations, leaving some gaps.

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 two concise sentences, front-loaded with the primary action and filters, and adds the key behavioral detail about default ordering and return fields. Every sentence provides value without unnecessary fluff.

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?

Given the tool's complexity (multiple filters, sorting, pagination), the description is somewhat minimal. It covers the main search dimensions and default sort, but doesn't mention limit/offset or other sort options. However, since an output schema is present, not explaining return values is acceptable. The description is adequate but could be more complete for a tool with this many parameters.

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 description coverage is 0%, so the description must compensate for parameter meanings. It lists the filter dimensions (text, number, subject, tag, type, status, due time) which maps to most schema properties, but it omits parameters like sort, limit, and offset, and does not explain their usage or formats. Thus, it partially compensates but is not exhaustive.

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's purpose: searching for problems (错题) using various criteria like text, number, subject, tag, type, status, or due date. It uses a specific verb '查询' (search) and resource, and distinguishes itself from sibling tools like get_problem by indicating it is a search/filter operation.

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 clear context on when to use this tool: when you need to search problems by any of the listed filters. It also mentions the default sorting behavior (by current week's priority), which is useful context. However, it does not explicitly name alternative tools or state when not to use this tool, so it's slightly 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?

With no annotations, the description's statement that archiving does not delete the problem, number, revision, or review history is a valuable, non-obvious behavioral guarantee. It addresses the destructive/non-destructive concern without contradicting any structured metadata, though it does not discuss other potential side effects.

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 a single, well-structured sentence with no filler. It front-loads the primary action and then adds a key qualifying statement, making it easy to parse and efficient.

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 and has an output schema, so return-value documentation is not needed. However, the description fails to explain the idempotency_key parameter and offers no usage context relative to update_problem, leaving some gaps for an agent preparing a correct invocation.

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 input schema has 0% description coverage, and the description only adds meaning for the 'status' parameter by listing its enum values. The 'number' and 'idempotency_key' parameters remain unexplained, leaving the agent to guess their purpose and format.

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's action ('set problem status') and the resource ('problem'), and explicitly lists the three allowed statuses: active, mastered, or archived. This distinguishes it from sibling tools like update_problem or adjust_priority, which focus on different attributes.

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 no guidance on when to use this tool versus update_problem, record_review, or other siblings. It only describes what the tool does, not the scenarios that call for it, and offers no exclusions or alternative recommendations.

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?

With no annotations provided, the description carries the burden of disclosing behavior. It reveals the optimistic concurrency requirement (expected_version), the conflict resolution approach (re-read), and an important invariant ('编号不会改变' - number will not change). This is valuable beyond the schema, though it does not mention potential side effects or idempotency semantics.

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 a single, front-loaded sentence that conveys the core purpose, the critical prerequisite, and a key invariant. Every clause earns its place with no redundancy or fluff.

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 description covers the essential action and concurrency mechanism, and an output schema exists to document return values. However, it omits guidance on constructing the patch object, the purpose of reason/idempotency_key, and partial-update semantics, making it less complete for a tool with 5 required parameters and no annotations.

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%, yet the description only explains one parameter (expected_version) and touches on '编号' (number) without detailing its role. The required parameters reason and idempotency_key are not explained at all, leaving the agent without sufficient understanding of why they are necessary or how to fill them.

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?

Description starts with '修正 OCR 文本、标签等内容' (correct OCR text, tags, etc.), clearly stating the action and target resource. This distinguishes it from sibling create_problem (creation) and get_problem (reading), making the purpose 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?

Provides a clear prerequisite: '必须传入读取时获得的 expected_version' (must pass expected_version obtained when reading), establishing when to use the tool relative to get_problem. It also advises on conflict handling ('冲突时重新读取'), but does not explicitly mention alternatives or when not to use it, so it falls short of full guidance.

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