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

Beyond the annotations the description discloses genuinely useful behavior: no-solution, multiple-solution, non-linear, or variable-denominator cases return "待复核" (pending review), and expressions must use explicit '*'. It does not address the side effects implied by readOnlyHint=false / idempotentHint=false, so the non-read-only nature of the tool remains unexplained.

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?

It is a single dense paragraph with the core purpose front-loaded and no filler; each clause (modes, examples, edge cases, scope) carries information. The density makes it slightly harder to scan, but nothing is wasted.

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 explained, and the description covers modes, format requirements, edge-case behavior, and scope limits. The main remaining gap is the absence of any mention of side effects, despite readOnlyHint=false.

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 params, and it does: it explains both values of `kind` and the default, the `expression` format (explicit '*', with examples), and `proposed_answer` (supplied without 'x=', e.g. 2). This meaningfully compensates for the empty schema documentation.

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 gives a specific verb+resource ("精确有理数验算") and then pins down the two exact verification modes it performs: polynomial identity in variable x and the unique solution of a simplified one-variable linear equation, each with concrete examples. It is clearly understandable in isolation, though it does not explicitly distinguish itself from related sibling tools such as review_practice_attempt or record_practice.

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 states when each mode applies (polynomial_identity is the default; linear_equation handles simplified linear equations) and gives worked examples for both. It also adds a scope exclusion – it only verifies the given expression and does not guarantee intent/answer matching or teaching effect – but it does not point to any alternative tool for those other needs.

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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false). It discloses that no upload occurs and the original is not overwritten, that PDFs reuse existing page rendering with no extra scaling/rotation and output page-1 PNG, that identical source bytes/region are reused while changed copies are rejected, that deleting the parent document removes this descendant, and that crops are not auto-recognized or PI-redacted.

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-loads the core action and its most important constraint (no upload, no overwrite), then layers in sequencing, reuse, and lifecycle facts. Dense but nearly every sentence adds distinct, decision-relevant information; a little consolidation would help, but nothing is padding.

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 annotations already cover the safety/idempotency profile. Within that context the description supplies the crop-vs-OCR coordinate constraint, the read_evidence/parse_document follow-up path, nesting/parent-tracing rules, and delete-cascade behavior — everything an agent needs to invoke and sequence this tool correctly.

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?

With 0% schema description coverage, the description must carry the load, and it does add key semantics: region must be a normalized region of the original page rather than raw OCR coordinates, and coordinates of the result belong to the crop (parent tracking via the crop field, traced layer by layer when nested). It still does not spell out the exact box ordering/coordinate range, so it stops short of fully defining the Region object.

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 and resource: locally crops a specified region of a page and returns an independent document_id plus parent page/hash/pixel bounds. It also distinguishes itself from siblings by explicitly clarifying it does not upload or overwrite the original, and by naming read_evidence and parse_document for the follow-up steps.

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?

Gives explicit sequencing (view the original page first, then pass a normalized region of the original page) and an explicit prohibition (cannot pass OCR coordinates of unknown orientation). It also routes follow-up work: use read_evidence to view the crop, and parse_document only if recognition is genuinely needed, noting this adds a new upload rather than being a free retry.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds substantial context beyond them: what the cascade actually includes (the full mixed export), what survives (input originals, external copies, backups, provider data), the absence of SSD physical-erasure guarantees, interruption/reconnection behavior, and that only a minimal receipt is retained. This is exactly the extra material an agent needs for a destructive tool.

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 dense paragraph, front-loaded with the action and the preconditions before the caveats. Nearly every clause carries non-redundant information, though the run-on packing of interruption behavior and non-deletion guarantees into one sentence slightly hurts scannability.

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 local cascade delete with an output schema present, the description covers scope, preconditions, refusal conditions, and survivor-set caveats thoroughly, so return values need not be explained. The remaining gap is the undocumented meaning/derivation of document_id and inventory_digest, which the agent must infer.

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% across all three required params. The description compensates partially by stating inventory_digest must be current and by clarifying that acknowledge_delete is an agent-relayed flag rather than standalone authentication, but document_id is never explained and the digest's format/source is left implicit. Partial compensation, not full.

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 opens with a specific verb+resource ('执行本地级联删除') and immediately scopes it against the sibling preview_document_deletion by requiring that tool's output to have been reviewed first. An agent can distinguish this destructive cascade from preview_document_deletion and redact_document without opening any 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?

It states explicit preconditions (user must have requested deletion AND seen the full preview_document_deletion impact), explains that acknowledge_delete is agent-relayed rather than an independent authorization gate, and gives explicit refuse conditions when other sessions or remote executions exist. When-to-use and when-not-to-use are both covered.

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?

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false; the description adds real value beyond them by disclosing the default record filter (only user-included, validated, re-checked records), what include_drafts unlocks, that the full export directory contains answers and original answers, and that nothing is auto-published or sent. This is meaningful behavior the annotations don't convey.

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 content is dense and front-loads the outputs, but it is a run-on sequence of semicolon-separated clauses mixing outputs, packaging warnings, defaults, and prerequisites. It is complete rather than wasteful, but the structure makes it hard to parse quickly.

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 semantics need not be spelled out, yet the description helpfully names practice_bundle_path and manifest_path and explains their contents. Combined with the default-filter explanation and the include_drafts note, most of what an agent needs is present; only record_ids's expected form remains unstated.

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 carry parameter meaning. It explains include_drafts well ('允许带待复核标记的草稿'), but record_ids semantics are only implied (records to export, subject to the default filter). Worse, it references 'clean_evidence_ids', which is not a parameter in the schema, creating confusion about the actual input surface.

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 first sentence states a clear verb (导出/export) and enumerates the concrete artifacts produced (错题本, 变式题册, 答案册, 原卷证据图). An agent immediately knows this produces a printable export bundle. It does not explicitly differentiate itself from siblings like query_errorbook or make_clean_copy, so it stops short of 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?

Strong contextual guidance: it names the downstream action ('给学生材料时使用此包并完整解压') and an explicit exclusion ('不要复制含答案的整个导出目录'), plus a prerequisite ('先read_study_record查看exercise_validation和clean_copy_validation'). This tells the agent when and how to use the output, though it does not explicitly contrast against any alternative 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?

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds real behavioral context beyond them: results are cached rather than resubmitted, polling must be spaced by at least 3 seconds, failed observations keep the job alive, and partial results require stating missing pages. These are concrete traits an agent needs that the annotations don't convey.

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?

Dense and front-loaded: purpose first, then polling behavior, failure handling, partial handling, and the parameter note. There is essentially no filler, though the run-on semicolon structure makes it slightly hard 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?

An output schema exists, so return-value documentation is not required, and the description covers the operational edges (poll interval, failure retention, partial results) that matter for correct invocation. The main gap is the absence of any alternative-selection guidance among the job-related 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 description coverage is 0%, so the description must carry the burden. It explains include_attempt_history meaningfully (returns the last 10 old attempts plus total count, full history stored locally), but job_id is left unexplained and only one of two parameters is addressed, so compensation is partial.

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 (查询既有TextIn任务并缓存完成结果) and adds the key qualifier 不重新提交, which separates it from a fresh submission. It does not name a sibling like resume_job_observation or list_parse_jobs to fully disambiguate, so it stops short of 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?

Gives operational guidance for pending/in_progress (wait at least 3 seconds between calls) and for failure (retain the job), which implies polling usage. However, it never states when to prefer this over resume_job_observation, list_parse_jobs, or retry_parse_document, so selection guidance is only implied.

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?

Annotations declare write semantics (readOnlyHint=false, destructiveHint=false, non-idempotent), and the description adds real behavioral context beyond that: rejection of directories/pipes/devices, color-original preservation, and the no-TextIn guarantee. It stops short of describing the failure/response behavior in detail, but the added constraints are 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?

One dense sentence front-loads the purpose and constraints (formats, size, location) before the caveats about rejected input types and TextIn. Every clause earns its place; only the trailing semicolon clause could arguably be split for readability.

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-path import tool with an existing output schema and full annotation coverage, the description supplies formats, size/page limits, rejection cases, and the no-TextIn boundary, which is nearly everything an agent needs. The only omission is the path-format detail, which is minor given the output schema handles 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?

With schema description coverage at 0%, the single 'path' parameter carries no format documentation. The description partially compensates by implying the path must point inside the dedicated materials directory and to a supported file type, but it never states whether the path is absolute/relative or its exact shape, so gaps remain.

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 (导入/import) and resource (PDF/JPG/PNG 文件), and adds scope qualifiers: local saved files, dedicated materials directory, 20MiB/20-page limits. The clause '不会调用 TextIn' distinguishes it from the parse_document sibling, so an agent can separate it from parsing tools without opening either 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?

Clearly frames the intended input (user-specified file already saved to the local materials directory) and implies use before parsing by noting TextIn is not invoked. It does not explicitly name an alternative sibling (e.g., list_input_files or parse_document) or state when-not to use it, keeping it below 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds pagination behavior and the cross-session ID-stability rationale, but discloses nothing about rate limits, ordering, or output shape.

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 tight sentence with the key purpose and rationale front-loaded; nothing is wasted. It is arguably terse to the point of omitting needed guidance, but structurally 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?

An output schema exists so return values need no explanation, and annotations cover safety. But for a list tool with two undocumented parameters, the description leaves gaps in pagination mechanics and when to prefer it over sibling list tools.

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% and both parameters (limit, offset) are undocumented. The description only mentions '分页' (pagination), which gestures at the two params but doesn't explain their meaning, defaults, or ranges, so it does not compensate for the coverage 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 gives a specific verb (pagination/retrieval) and resource (已导入材料, imported documents) and highlights the key output trait (real IDs). It is clear what the tool does, though it does not explicitly distinguish itself from siblings like list_input_files or list_parse_jobs.

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?

'避免跨会话猜测 ID' implies the use case (fetching authoritative document IDs so you don't guess across sessions), which is useful implied guidance. However, no explicit when-to-use/when-not or named alternatives are provided.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it explicitly says the tool does not read content, import, or upload, and clarifies that size compliance does not prove format/page-count validity or constitute user authorization. These boundary disclosures are the kind of context annotations cannot express.

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 dense but front-loaded: purpose and scope come first, followed by caveats, pagination, and the sibling pointer. Every clause adds signal, though the caveat cluster ('does not read/import/upload' plus the validity and authorization disclaimers) is slightly heavy for the amount of behavioral difference it conveys.

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 (covering next_offset), and annotations cover safety, so the description need not explain return values. Given full context, it supplies trigger conditions, scope limits, non-actions, pagination behavior, and the alternative tool – nothing an agent needs to invoke it correctly is missing.

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 carries the burden. It explains pagination via next_offset and first-page refresh, but never defines the offset or limit parameters themselves (e.g., units, max limit, default of 20), so it only partially compensates for the coverage gap. Baseline 3 is appropriate.

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 (paginated list) and resource (first-level PDF/JPG/PNG candidates in the configured input directory) with explicit scope constraints. It names the sibling list_documents as the alternative for already-imported materials, so an agent can distinguish it without opening a 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?

It states the trigger scenario (user wants to view materials pending import) and the exclusion/alternative (use list_documents for imported materials). It also explains the pagination workflow (continue with next_offset, refresh the first page when the directory changes) and warns that actual import still requires per-file checks.

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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, but the description adds substantive behavior beyond them: it queries only local records, does not read source files or TextIn, and does not resubmit or resume jobs. It further warns that status is not proof of remote liveness and that completed/partial does not guarantee cache-file integrity, which is high-value operational context.

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?

Dense but front-loaded: the core purpose and the when/when-not routing come first, followed by status caveats. Nearly every clause earns its place, though the multi-clause status discussion is slightly heavy for a list tool.

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 explained. The description covers the retrieval flow, local-only constraint, status interpretation caveats, and downstream tool routing, leaving nothing an agent needs to call it correctly.

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 parameter meaning. It clarifies that document_id comes from list_documents and that offset drives pagination (next_offset), which adds real value, but it never explains limit semantics or its default. Partial compensation for a fully undocumented 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?

States a specific verb and resource: cross-session recovery of saved parse job IDs, mode, and status for a given document. It explicitly distinguishes itself from siblings parse_document, get_job, and read_document, so an agent can tell them apart without opening any 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?

Gives explicit prerequisites (call list_documents first to obtain the material ID) and pagination flow (read next_offset). It names alternatives with conditions: use read_document for existing results, get_job for other statuses, and explicitly warns not to call parse_document just to recover IDs.

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?

Beyond the annotations, it discloses the cost (paid TextIn call), that the source is preserved (consistent with destructiveHint=false), that output quality needs human/visual verification (question-stem damage), and that repeats do not resubmit (matching idempotentHint=true). It still omits where the resulting copy goes or how it is retrieved.

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 dense sentence front-loads the key precondition (only when blank re-practice is needed) and then covers cost, preservation, verification, and idempotency without 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?

For a one-parameter, paid, external-call tool with no output schema and annotations already covering the safety profile, the description covers when to call and the caveats. It remains incomplete on the return artifact and retrieval path, which matters for a tool that produces a new copy.

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 evidence_id has no description, but the prose references a 'saved evidence crop', implicitly tying evidence_id to that object. This adds a little meaning but no format, sourcing, or validation detail, so it only reaches the baseline-with-partial-compensation level.

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 action (create a blank/clean copy of a saved evidence crop by having TextIn erase it) and states the outcome (the original stays unchanged). It is distinguishable from siblings like read_evidence or crop_document, though it does not explicitly name a sibling for contrast.

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 gives a clear trigger condition: call only when the user needs a blank question for re-practice. It also flags that the call is paid, which is real usage guidance. It does not, however, compare against an alternative such as re-reading or re-cropping the evidence.

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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, openWorldHint=true) by disclosing credential/billing requirements per mode, size and timeout limits, that uploads still occur in free_sync, that duplicate calls reuse failed/uncertain tasks, that redacted-copy changes are rejected, and that quotas are provider-controlled. The idempotent hint is reinforced and explained rather than merely repeated.

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?

Nearly every clause carries real operational information, but it is delivered as one dense semicolon-chained block rather than front-loaded, scannable structure, making the mode contracts and constraints harder to extract than they need to be.

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?

Covers credentials, billing, size/timeouts, retry/idempotency semantics, redaction preconditions, and where outputs are read (read_document/read_element/read_evidence); with an output schema present it need not describe return values. The only gap is the meaning of document_id itself.

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?

With 0% schema description coverage the description must carry the load, and it defines the mode enum exhaustively (paid_async/free_sync/vlm_sync semantics) and the max_paid_pages 1–20 ceiling. document_id is only indirectly explained (use the redacted copy's new ID), leaving one of three params under-specified.

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 opening states a concrete verb+resource ('上传指定材料到TextIn') and the body names the mode-specific behaviors that constitute parsing, plus it explicitly routes to sibling tools (redact_document, read_document, read_element, read_evidence). It never plainly says 'parse the document and produce structured output,' so the core action is implicit rather than stated, but an agent can still distinguish it 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?

Gives explicit when/when-not guidance: use paid_async (default, billed), free_sync for credential-free small inputs, vlm_sync only for already-imported single PNG/JPG; modes never auto-switch; repeated calls must reuse the same mode and must not be used to bypass retry protection; and it prescribes the redact-first flow when personal data is present. Alternatives are named rather than left to inference.

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?

Beyond the readOnly/idempotent annotations, it discloses pagination continuation via next_offset, that a changed digest invalidates prior reads, that an 'unresolved' state means the list is not complete, that symlinks are not followed, and that external files/copies/backups/provider data are out of scope. This is unusually rich behavioral context.

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 dense and front-loaded, leading with the read-only guarantee and impact scope. Every clause carries operational meaning, though the run-on punctuation makes it slightly harder to parse.

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. Given the tool's complexity, the description covers scope boundaries, pagination, digest invalidation, completeness criteria, and the handoff to delete_document — nothing essential is missing.

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. It explains next_offset-based continuation (covering offset/limit indirectly) but never defines limit/offset semantics or the document_id contract, leaving gaps for a low-coverage 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?

The opening clause names a specific verb (read-only check / 只读检查) and resource (document deletion impact), and explicitly negates the destructive alternative with 绝不执行删除. An agent can immediately distinguish this from delete_document in the sibling list.

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 states the gating condition for the destructive counterpart: delete_document may only be called after a complete list exists and the user has given an explicit instruction. That is clear routing guidance, though it does not explicitly enumerate other preview/listing alternatives.

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?

Goes well beyond the readOnly/idempotent annotations: no re-OCR, a 12000-byte cap on the JSON summary set that forces continued paging via next_offset even when results are fewer than limit, and the instruction to refresh the first page after mutations during paging. It also warns that summaries may contain hints that must not be shown before independent answering.

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?

Purpose and matching rules are front-loaded, and nearly every clause adds distinct information (byte cap, pagination, verdict-vs-status distinction). It is dense and semicolon-heavy, but not padded.

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?

Even though an output schema exists, the description usefully documents pagination via next_offset and the byte cap that governs return size, plus the important semantic gap between agent_verdict and review_status. An agent has everything needed to call and page this tool correctly.

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?

With 0% schema description coverage the description carries the load and does so well: it explains search matching rules, each filter dimension (review_status, agent_verdict, subject, document_id, knowledge_point), intersection semantics, and null/default meaning. It leaves limit/offset semantics only implicit through the pagination discussion.

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?

Opens with a specific verb+resource ('查当前错题文本') and immediately defines the matching semantics (case-insensitive literal substring, no internal field names/IDs/old history, no wildcard or Anki syntax). This clearly separates it from siblings like export_errorbook and read_review_queue, which serve different purposes.

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?

Gives actionable when-to-use guidance: filters intersect, omission means 'all', and practice selection should explicitly pass review_status=include since excluded items are included by default. It does not name a sibling alternative for the export/history cases, so it stops short of a full routing rule.

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?

Annotations already cover readOnly/idempotent/non-destructive, yet the description adds substantial behavioral context: empty chunks do not mean blank or unanswered, Success/completed does not prove transcription completeness, review_hints are for locating images not error judgment, and format is textin_vlm_v4 without fabricated elements or confidence. This is exactly the value-add beyond structured fields.

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 purpose is front-loaded and the content is dense but mostly earned. However, the same warning is repeated ('空分块不等于空白或未作答' and '无元素/分块不等于空白或漏答'), and the paragraph strings together many caveats without structure, reducing scannability.

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-value explanation is unnecessary, and the description correctly focuses on interpretation caveats (empty results, completeness of transcription, format differences) that an agent needs. It is nearly complete, missing only parameter-level guidance.

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% and the schema only exposes bare titles for job_id/limit/offset. The description implies pagination ('分页读取') but never explains the meaning, defaults, or units of limit/offset or what job_id must reference, so it fails to compensate for the coverage 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 opening sentence '分页读取已缓存结果' (read cached results with pagination) states a specific verb+resource, and it names what each parse format returns (elements/page_summary for xParse, chunks/image_metadata for vlm_sync). It distinguishes itself from siblings by pointing to read_evidence and read_element for specific needs, though the heavy caveat load dilutes immediate clarity.

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 gives explicit routing: use read_evidence to verify images because VLM position isn't mapped to the original page, and use read_element for full chunks/image metadata. That is clear when-to-use-this-vs-alternative guidance. It lacks explicit exclusion conditions for the tool itself, but the sibling routing is genuinely helpful.

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?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context they cannot: no API calls (served from cache), the subtle meaning of complete (covers only this return, not the field), truncation behavior with limit, and a caveat that VLM coordinates are unmapped and confidence/direction/labels must not be treated as grading conclusions.

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?

Dense but front-loaded and mostly earns its length, since nearly every clause is an invocation rule. It is on the verbose side (backend section mapping, pagination, format handling, caveats all in one block) and could be tightened, but nothing is purely redundant.

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-shape explanation is not required, and the description covers everything else an agent needs: section selection, pagination loop, JSON vs text handling, and the VLM interpretation caveats. Nothing required for correct invocation is missing.

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 it does: offset is defined as a character position, limit's max is 8000 with a note that a single return may be shorter, and section is fully enumerated with per-value meaning. The two required identifiers are covered by the instruction to keep job_id/element_index stable across pages.

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 and resource (paged reading of cached element fields, no API calls) and immediately scopes it by enumerating the selectable sections for both xParse and VLM backends. An agent can tell this apart from sibling readers like read_document or read_evidence without inspecting either 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?

Gives explicit routing: which section to use per backend (element/text/metadata/page), the exact continuation protocol (start at offset=0, hold job_id/element_index/section constant, follow next_offset until null, never infer position from limit), and the concatenation rule (ordered, parse JSON only when format=json). It even warns that complete is not a stop condition.

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?

Beyond the annotations, the description discloses meaningful behavior: orientation is not guaranteed, no external API is called, padding is bounded to 0–0.1, and it explains the returned evidence ID, region, and view_rotation_ccw plus a recovery path. It does not, however, reconcile why a 'read_' tool carries readOnlyHint=false and idempotentHint=false, leaving that annotation profile unexplained.

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 purpose is front-loaded in the first clause, which is good, but the rest is a run-on packing limitations, return values, and a recovery procedure into one dense paragraph without clear separation. Little is pure waste, but the lack of structure hurts scanability.

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 output schema, the description usefully enumerates return fields (evidence ID, original-page region, view_rotation_ccw) and describes the inversion-recovery workflow, covering what an agent needs to chain into read_evidence. The main gap is the undocumented required parameters, but overall it is sufficient 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 for all three parameters. It only adds meaning for padding ('0–0.1边距'), while the two required parameters job_id and element_index receive no description in either the schema or the text. Partial compensation only.

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: cropping an image by OCR element coordinates and rotating it per the upstream report's page orientation. It also names the sibling read_evidence as the fallback, so an agent can distinguish this from the whole-page read tool. The phrasing is dense and clause-heavy, which slightly blunts immediate comprehension.

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 gives explicit when-not conditions ('仅支持未变形、未跨页合并、页码与角度有效的结果') and routes to the alternative read_evidence for those cases. It adds a second conditional branch for inverted views, telling the agent to pass the returned document_id and region as-is to read_evidence without re-rotating. Both the alternative tool and the selecting conditions are named, leaving nothing to inference.

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?

Annotations exist but are notable: readOnlyHint=false on a tool whose description frames it purely as a fetch of an image and an ID, which implies possible side effects (e.g. evidence creation/caching) that the description never explains. The description does add real behavioral value by defining the coordinate contract and orientation caveat, but it says nothing about permissions, limits, or what side effects accompany the call.

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?

Dense but front-loaded: the return value comes first, then the coordinate semantics, then the orientation warning. Every clause earns its place; it is slightly terse given the tool's read/return nature, but there is 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?

With no output schema, the description correctly states what is returned (page image and evidence ID), and it covers the non-obvious coordinate formats for both required parameters. Remaining gaps are minor: no mention of side effects hinted at by readOnlyHint=false, no sibling differentiation.

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 parameter burden, and it does: region.page is 1-based and box is a normalized [left,top,right,bottom] on the original page, with the [0,0,1,1] full-page convention explained. It does not mention the page maximum of 20 from the schema, but document_id is self-evident.

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: returns the original-page evidence image plus an evidence ID. That clearly separates it from generic document reads like read_document or read_element. However, it never distinguishes itself from the very similar sibling read_element_evidence, leaving the agent to guess which evidence reader to pick.

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 procedural guidance for the region parameter (start with [0,0,1,1] for the full page, then narrow down) and a warning not to reuse OCR coordinates of unknown orientation. That is useful, but there is no explicit when-to-use / when-not-to-use guidance relative to the alternatives (read_element, read_element_evidence, crop_document).

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?

Annotations already cover the read-only/idempotent/non-destructive safety profile, and the description adds real value beyond them: a hard cap of 20 records and 80000 serialized characters, the pagination cursor protocol, and two explicit non-goals. It does reference output-side fields (next_before_revision, current_feedback_revision) rather than only input behavior, but the constraints it discloses are genuinely useful.

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?

Purpose is front-loaded and followed by pagination mechanics, limits, and non-goals in a compact block with no filler. It is dense but every clause carries a constraint or routing signal, so little is wasted.

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 the description needn't explain return values, and it correctly focuses on call mechanics and scoping. The only shortfall is leaving the required attempt_id and the limit range ambiguous, but overall an agent has enough to invoke it correctly.

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 carries the burden, and it only partially compensates. It implies a 20-item ceiling tied to limit and explains the continuation cursor, but the input parameter name is before_revision while the description calls the continuation value next_before_revision, and attempt_id's role/format is never 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?

States a specific verb+resource with scope: reads the feedback for one attempt plus all historical revisions. It distinguishes itself from pure-history or review tools by adding non-goals ('doesn't judge right/wrong', 'doesn't schedule review'), though it never names the sibling tools directly.

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?

Gives clear operational context for pagination: continue with next_before_revision until null, and use current_feedback_revision as 0 on first call. It also states exclusions ('不判断对错', '不安排复习'), which routes an agent away from review_practice_attempt/review_study_record, but does not explicitly prescribe when to choose this over those siblings by name.

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?

Annotations already declare a safe read-only, idempotent operation, yet the description still adds substantial non-obvious behavior: page caps (20 items / 80000 chars), that detailed results contain answers and must not be surfaced pre-practice, cursor-based pagination, and that old records may lack snapshots so current question text must not be substituted and mastery must not be auto-judged.

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?

Purpose, mode selection, and pagination/edge-case constraints are front-loaded and every clause carries operational meaning. It is dense and somewhat terse, but there is 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?

An output schema exists so return values need not be restated, yet the description still surfaces the edge cases an agent needs (missing snapshots, sensitive answers, cursor termination at null). Nothing required to invoke or interpret the tool is missing.

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 carries the full burden, and it does: include_details semantics, the before/next_before continuation contract, and an implied per-page limit. record_id is only loosely implied ('某题'), leaving a small 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?

States a specific verb and resource: reading the original/variant answer history for a given question, with the default-summary vs. detailed modes. This clearly separates it from siblings like read_practice_prompt and read_practice_feedback, though it never explicitly names an alternative to route against.

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?

Gives operative usage rules: default to summary, set include_details=true for full data, do not display detailed results before an independent re-practice, and continue via next_before (not page numbers). It stops short of explicit when-to-use-this-vs-sibling 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?

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral detail: exclusions (no original tags/subject/old answers/analysis/feedback), no OCR or erasure, clean_images returns hash-verified net images with a 12MiB cap, and refusal on missing/changed/unverified images with no fallback. This is valuable transparency beyond annotations.

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 dense run-on paragraph with multiple clauses separated by commas and semicolons. While every clause conveys information, it is not front-loaded or structured, making it harder to parse quickly. It could be reorganized with bullets or clearer separation.

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 five parameters, no output schema, and a complex set of preconditions, the description covers many edge cases and behavioral rules. However, it omits any explanation of the two required identifiers (record_id, expected_revision) and gives only a hint about the return (record_id/source_revision). An agent would still lack enough to call the tool confidently.

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 carries the full burden. It explains presentation (text vs clean_images) and practice_kind (original vs exercise/variant) to some degree, but never defines the required record_id or expected_revision, nor clarifies exercise_index beyond '变式需下标'. Critical parameters remain unexplained.

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 action: '练习前只取当前版本题面与中性display_label' (before practice, fetch only the current version question text and neutral display_label). It distinguishes this from fetching original tags, subject, old answers, reference answers, analysis, or feedback. However, it does not explicitly name sibling alternatives like read_element or read_document, so an agent must infer the differentiation.

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 gives a clear context ('练习前') and preconditions ('题目须已纳入；变式需下标及答案检查通过，只支持text'), plus a warning not to treat the read tool as proof of independent answer. But it does not explicitly say when to use this versus other read tools or what to do if preconditions fail beyond refusal.

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?

Annotations already cover readOnly/idempotent/non-destructive/closed-world, yet the description adds real behavioral context: pagination caps (每页最多20条), how to continue (next_before_revision), initial revision semantics (首次0), and a display caution about hint-containing history. This is meaningful value beyond the annotations.

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?

Purpose is front-loaded in the first clause, then pagination, then the sibling redirect, then the display caution — each clause carries a distinct fact with no filler. The semicolon-separated structure keeps it dense but scannable.

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-value shape needn't be restated, and the description still covers pagination, cursor continuation, initial-revision behavior, and the alternative tool for queue status. For a read-only paged tool this is sufficient to invoke it correctly.

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 carries the burden. It clarifies before_revision as a pagination cursor ('next_before_revision继续') and limit as a page size ('每页最多20条'), but record_id and the relation of these fields to the returned current_plan_revision/source_revision remain only loosely explained.

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+resource ('读取某题复习计划和全部修订') and explicitly separates itself from the sibling read_review_queue by assigning '是否到期或需重新核对' to that tool. An agent can distinguish its job without opening a schema. Not a 5 only because the scope of '全部修订' is left somewhat open.

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 routes one decision to an alternative ('当前是否到期或需重新核对见read_review_queue') and hints that history shouldn't be shown before independent re-practice, but it never states the core conditions for calling this tool versus read_study_record or read_practice_history. Usage 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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds substantial non-obvious behavior: labels are omitted by default, include_labels may leak answers/error hints, status semantics for scheduled/outdated/completed, offset pagination invalidation on plan changes, and the absence of background notifications or interval algorithms.

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?

Dense and front-loaded: purpose, default behavior, the include_labels tradeoff, status semantics, then pagination caveats. Every sentence carries information, though the block is packed and could be marginally tightened.

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-format explanation is unnecessary. Given a 5-param, 0%-coverage schema, the description supplies the semantics, risks, and caveats an agent needs to invoke it correctly. Nothing major is missing.

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?

With 0% schema description coverage the description must carry the load. It explains as_of (must include timezone), include_labels (default false; what it reveals and the risk), status meanings for several enum values, and offset pagination behavior. It does not cover limit or the due/cancelled/all status values, leaving a small 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?

States a specific verb (读取) and resource (到期复习队列) with scope (default current time, due queue). It is clearly distinguished from sibling review tools such as read_review_plan, update_review_plan, and review_practice_attempt, which serve different intents.

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?

Gives concrete when-to-use context: '整理题库时可显式include_labels=true' and a when-not warning '勿在独立重练前展示'. It doesn't explicitly name an alternative sibling tool, but the operational conditions for the key optional parameter are clearly 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?

Annotations already declare a safe, idempotent read, but the description adds real behavioral context: the two-layer return shape (outer id/revision/review_status/exercise_validation vs inner record), that a snapshot read omits live checks, that nonexistent revisions are rejected with no fallback, and that history may contain answers. This goes well beyond the structured hints.

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 core usage rule is front-loaded and each sentence adds a distinct fact (return shape, snapshot semantics, error behavior, alternatives). It is dense and somewhat run-on, with several clauses packed into single sentences, but there is little waste.

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 two-parameter read tool this is complete: reading behavior, revision branching, return-layer structure, rejection behavior, and the alternative tool are all covered, and an output schema exists so return values need no further explanation.

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 carry the param meaning, and it does for the non-obvious 'revision' (default/omitted = live current, positive integer = frozen snapshot, cannot be used to increment and write back). It does not describe record_id, though that parameter is self-evident.

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 (read a study record) and clarifies what is read: the current question plus real-time checks. It also routes independent re-practice to the sibling read_practice_prompt. Sibling differentiation against read_document/read_element/review_study_record is not spelled out, keeping it short of 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?

Explicit when-to-use is given ('read before updating'), with the key branch stated up front: omit revision to get the current version and live checks, pass a positive integer revision to read a saved snapshot. It names the alternative for re-practice (read_practice_prompt) and warns current_revision cannot be used to write an old record back.

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 behavioral context beyond annotations: it declines to grade or judge mastery, forbids inferring 'independent' assistance from a correct answer, preserves source_revision/snapshot history, and states that conflicting duplicate submissions are rejected rather than overwritten. Note the conditional idempotency via attempt_key sits in tension with idempotentHint=false, though it is scoped to matching keys so not a hard 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?

A dense but front-loaded paragraph that leads with purpose before parameter guidance, with each clause carrying new information. It runs slightly long and packs many constraints into one block, but there is little 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?

Output schema exists so return values need not be described, and annotations cover the safety profile. For a 7-parameter mutation tool the critical semantics (assistance, attempt_key, exercise_index) are covered, though required fields expected_revision and response are never addressed.

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?

With schema description coverage at 0%, the description must compensate and largely does: it explains exercise_index vs practice_kind, the four assistance enum values and their non-inferability, and the attempt_key retry/dedup contract. It leaves response, record_id, and expected_revision semantics unexplained, so it is strong but not complete.

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 and resource ('记录...再次作答') and immediately bounds the scope by declaring what it does NOT do ('不自动判分或判定掌握'), which cleanly separates it from grading-oriented siblings like check_exercise and review_practice_attempt.

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?

Gives concrete when-to conditions: default exercise requires a 0-based exercise_index while 'original' passes none, and recommends generating attempt_key per attempt with same-key retries for idempotency. It does not explicitly name an alternative sibling or a when-not-to-use-this condition, so 4 rather than 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?

Beyond the annotations (readOnlyHint=false, non-destructive, non-idempotent), the description discloses a great deal: the copy is not uploaded and does not overwrite the source, the PDF is rasterized page-by-page removing text layer/form/attachments/metadata, small-text quality may degrade, interactivity is lost, repeated identical regions reuse the copy, and a changed copy file blocks reuse. It also notes a prior upload cannot be retracted. This is rich behavioral context beyond what annotations provide.

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 core action and its non-destructive guarantee are front-loaded in the first clause, and every sentence carries substantive information (limits, side effects, reuse rules). It is dense and semicolon-heavy, but there is little filler to cut.

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 write operation with a 0%-coverage schema, this description is notably complete: it covers mutation semantics, side effects, irreversible prior-upload implications, reuse behavior, and downstream workflow. An output schema exists, so return-value detail is not required, and the mention of document_id is a bonus.

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 burden, and it does add meaning: regions are 1-100 normalized regions on the original pages. This clarifies the count constraint and coordinate normalization that the bare schema does not. document_id itself is self-evident, and box inner formatting is left to the schema, so not a full 5.

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+resource (locally redact regions of a document), specifies that it returns an independent copy document_id, and explicitly says it does not upload or overwrite the original. The privacy-redaction purpose ('遮盖指定姓名/学号等区域') is distinct enough that an agent can differentiate it from generic mutation 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?

It sets clear context: the agent must supply regions itself because PII is not auto-detected, and it warns to inspect all copy pages before uploading. It also directs downstream workflow (parse_document/read_evidence/save_study_record use the new ID) and reuse rules. However, it never explicitly contrasts with the closest siblings (crop_document, make_clean_copy) that might otherwise be chosen.

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 description adds substantial behavior beyond the annotations: no re-upload/re-parse, idempotency semantics ('同一版本的恢复决定不会重复应用', consistent with idempotentHint=true), the 40306 re-stop rule, and a minimum 3-second query interval. It does not contradict any annotation (readOnlyHint=false fits a state-changing resume).

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 single dense paragraph front-loads the key condition (only resume on explicit user request) and each subsequent clause carries distinct information, with no filler. It is somewhat run-on and would benefit from sentence breaks, but every statement 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?

An output schema exists, so return values need not be explained. Given the complex rate-limit/idempotency semantics involved, the description covers the necessary behavioral context well; the main gap is that the four required parameters (0% documented) receive only partial explanation.

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 full burden. It compensates partially: it explains that expected_attempt and expected_observation_revision come from get_job and that missing values default to 1 and 0, and it constrains user_note's meaning. However, it does not describe format or usage of job_id and only loosely characterizes user_note's required content.

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+resource: resume querying the original job observation after rate-limit 40306 handling, and explicitly scopes out re-uploading/re-parsing. An agent can distinguish it from generic parse/get_job siblings, though the opening precondition ('限流40306处理后') makes the core purpose slightly context-dependent rather than front-loaded.

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 gives an explicit trigger ('仅在用户明确要求时恢复') and a stop condition ('再次40306仍停止'), plus a prerequisite step (先 get_job 取得 attempt_number 和 observation_revision). It lacks explicit naming of alternative tools to prefer, but the when-to-use and when-to-stop guidance is clear.

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?

Goes well beyond the annotations: discloses duplicate-billing risk, the one-request-per-expected_attempt idempotency guard, that old attempts are preserved, how to treat missing attempt_number as 1, and that user_note is a host-agent relay rather than authenticated identity. These are material behavioral facts not derivable from the schema.

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-loads the consent precondition, then procedurally layers prerequisites, prohibitions, and edge cases. Dense but essentially waste-free; slightly packed for a single paragraph.

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 no explanation, and the description covers the risky-operation context well. The main remaining gap is semantics for the two cost/acknowledgement parameters, which matters because the tool can incur charges.

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 parameter meaning. It explains expected_attempt (derive via get_job, default 1) and user_note (relayed, not independent auth), but leaves job_id, max_paid_pages, and acknowledge_resubmission to be inferred from their bare names.

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 (重提/retry a parse document) and narrows scope to failed/submission_unknown tasks, which distinguishes it from parse_document and get_job. An agent can identify this as the escalation path for stuck jobs 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?

Explicit when-to-use ('仅在用户明确同意重新上传/可能重复计费后'), when-not ('禁止自动重试或切换模式'), a required prerequisite ('先get_job取得attempt_number'), and routing for blockers ('凭据/额度问题应先处理；40306先联系服务商'). This is a complete decision procedure.

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?

Annotations only declare readOnly=false, idempotent=false, destructive=false, openWorld=false, so the description carries real additional weight: it will not rewrite the answer, question, or original grading, refuses to auto re-grade attempts lacking a snapshot, and preserves the old feedback on a revision. The withdraw mechanism and its constraints are also disclosed. This is substantial context beyond the annotations and is fully consistent with them.

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?

Purpose is front-loaded, followed by prerequisites, then per-field semantics and edge cases, so ordering is logical. The prose is dense and run-on in places, and mentions user_opinion_source_revision, which does not appear in the input schema. Every sentence still carries distinct information, so waste is low.

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 needn't be described, and the description instead covers the workflow, defaults, conflict handling, and mutation limits an agent needs. The only gap is the reference to user_opinion_source_revision, which is absent from the schema, creating a small traceability mismatch.

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% (only withdraw_user_opinion carries an inline note), so the description must compensate and largely does: it defines agent_verdict as the Agent's analysis, sets user_verdict's default of unreported and the condition for filling it, explains user_note fidelity rules, and clarifies withdraw_user_opinion's required companion fields. The attempt_id and expected_feedback_revision semantics are covered only indirectly via 'current_feedback_revision'.

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 opening states a specific verb and resource: saving Agent feedback plus follow-up suggestions onto a historical practice attempt, and immediately bounds it ('不能替代自动判分或掌握判定'). It effectively separates itself from siblings by naming read_practice_history and read_practice_feedback as adjacent-but-different tools. It stops short of a 5 only because the tool name ('review_') slightly undersells that the action is a save/write.

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?

Explicit when-to-use and prerequisites: call read_practice_history(include_details=true) to verify the original prompt/answer, then read_practice_feedback to obtain current_feedback_revision (0 on first call). It also gives conditional rules for edge cases — fill user_verdict only on explicit user statements, use withdraw_user_opinion=true only on explicit withdrawal, and read first on version conflict.

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 substantial behavioral context beyond annotations: no substitution of model confidence for user opinion, the dependency of approved_clean_copies on sha256 values from read_study_record, default empty confirmations, resubmission requirements after changes, and a caveat that user_note is relayed by the host agent rather than independently authenticated. It does not cover permissions, concurrency, or what data may be overwritten, so a 5 is not warranted.

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 dense but purposeful paragraph that front-loads the core rule about transcribing user opinions. Every sentence carries operational guidance, though it could be more scannable with explicit structure for the approval rules.

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 mutation tool with 6 parameters, 0% schema coverage, and an existing output schema, the description supplies rich workflow, dependency, and resubmission constraints. It still omits explanation of expected_revision (likely concurrency control) and record_id, so it is not fully complete.

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% across 6 parameters, so the description must compensate. It explains decision values (include/exclude/uncertain) implicitly, approves exercise indices starting from 0, the approved_clean_copies mapping format, and user_note purpose, but leaves record_id and expected_revision without added meaning, resulting in only partial compensation.

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 (review) and resource (study_record), and the core rule of transcribing user's explicit include/exclude/uncertain opinions. It references read_study_record as the source of sha256, helping distinguish it from that reader, but does not explicitly contrast with save_study_record or review_practice_attempt, keeping it from 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?

Provides clear conditional guidance for when to populate approved_exercise_indices and approved_clean_copies, notes both default to empty, and requires resubmission after modification or re-review. It does not name alternative tools or state when not to use this tool, so it stops short of full when/when-not 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?

Far beyond the annotations (which only say non-readOnly, non-idempotent, non-destructive), it discloses that missing optional fields revert to defaults, that every save returns to 待复核, and precisely which field edits (stem/answer/main evidence/annotations/paper grading/agent verdict) wipe analysis and exercises. There is mild tension with destructiveHint=false given the described clearing of derived data, but the reset is intentional and regenerable rather than destructive loss.

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 most important constraint ('完整保存...不是局部patch') is front-loaded, and each clause carries distinct information (workflow, defaults, reset, clearing rules). It is dense and somewhat run-on with several clauses packed into long sentences, but there is 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?

For a complex full-record mutation with a rich output schema (so return values needn't be spelled out, though it mentions them anyway), the description covers workflow, default handling, review-state transitions, and destructive side effects. Only the semantics of individual nested record fields are left to the 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?

With 0% schema description coverage on 3 params and a large nested StudyRecord, the description carries the load: it explains the record_id/expected_revision mapping to the outer id/revision and clarifies clean_evidence_ids semantics ('按题面顺序选取本题主证据已生成的净题图，不自动确认'). It does not explain the many inner record fields individually, so it compensates well but not completely.

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 and resource (完整保存题目草稿) and immediately distinguishes the operation from its sibling: '不是局部patch' and the contrast with read_study_record. An agent can tell this is a full-record upsert, not a partial write, 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?

It prescribes the exact workflow and conditions: read_study_record first, modify the returned record, pass it back whole, and map the outer id/revision to record_id/expected_revision. It also states the ordering constraint for corrections (save the basis first, then regenerate) and the reset-to-pending behavior after each save.

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?

Goes well beyond the annotations by disclosing optimistic-concurrency behavior ('two independent versions', read-before-write on conflict, no auto-overwrite), side effects (does not auto-reschedule dates), and the semantic distinction between 'completed' vs 'independent/mastered'. With destructiveHint=false and idempotentHint=false already declared, this adds the real behavioral context an agent needs.

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?

Purpose is front-loaded in the first clause and every sentence carries content, but the single dense paragraph with semicolon-chained clauses is heavy to parse. It is appropriately sized for a 4-parameter mutation tool, just tightly packed.

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; what remains — preconditions, concurrency handling, side effects, and the original/exercise branching — is all covered. Nothing an agent needs to call this multi-action tool correctly is missing.

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 largely does: it explains due_at's timezone requirement, user_note fidelity, practice_kind defaulting to original, exercise_index for the exercise branch, and attempt_id semantics for complete. The expected_record_revision / expected_plan_revision fields are only implied by the version-conflict prose rather than named, leaving a small 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?

States the specific resource (review plan) and the three verbs it performs (schedule / complete / cancel), plus the scope 'one question, original or variant'. It is clearly distinguishable from siblings like read_review_plan and record_practice, which the description names as prerequisites.

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?

Gives explicit, per-action preconditions: read_study_record and read_review_plan first, schedule requires an already-incorporated question plus a timezone-bearing due_at and faithful user_note, exercise requires an index and a passing answer check, complete requires an attempt saved after scheduling. It also states what the tool does not do (no auto-reminders).

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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and non-open-world behavior, so the safety profile is covered. The description adds meaningful context beyond annotations: it clarifies runtime_version semantics (load-time package version, not proof of functionality/completeness) and states that no secrets are displayed and no external APIs are called. These are useful behavioral limits.

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 compact and front-loaded with the primary checking scope. The semicolon-separated clauses about runtime_version and the no-secrets/no-API constraints are relevant, though the first clause is broad enough that the overall text remains slightly dense rather than optimally crisp.

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, the description need not explain return values, and the rich annotations already cover safety behavior. The description adds privacy and external-API limitations plus runtime_version semantics, making it complete enough for a parameterless workspace-check tool, though 'implementation boundaries' remains abstract.

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 input parameters, and schema description coverage is 100%, so the baseline score is 4. The description mentions runtime_version, but that is an output concept rather than an input parameter, so it does not alter the parameter semantics score.

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 (检查/check) and the resources it inspects: configuration, import directories, and implementation boundaries. It is unique among the sibling tools, which are document and practice/review operations, so no sibling differentiation is needed. However, it does not explicitly say it returns workspace status information, leaving the exact output purpose slightly implicit.

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 describes what the tool checks, but gives no explicit when-to-use guidance, no prerequisites, and no alternatives to consider. An agent must infer that this is a diagnostic/status tool from the name and vague opening clause. No usage conditions are stated.

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