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

With no annotations, the description carries full behavioral disclosure. It explicitly states two side effects (course_id auto-fill, concept_ids auto-registration) and even warns '不应该' (should not) manually update, which prevents misuse. This adds significant context beyond the schema, though it does not mention return values or error behavior.

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?

Two dense, front-loaded sentences with zero filler. The first verb phrase immediately states the action, and the second sentence adds critical constraints in an efficient manner. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is adequate for basic use, covering key auto-behaviors. However, with moderate parameter complexity (5 params, nested source_refs) and no output schema, it omits return values, error cases, and the purpose of source_refs/short_definition. It leaves some gap in fully guiding an agent through invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 40%, and the description adds no explanation for 'name', 'short_definition', or 'source_refs'. The only parameter-related note is that course_id is NOT needed, which is helpful but does not compensate for the low coverage. The description does not assist with interpreting any of the actual schema parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with '为 lesson 添加一个 concept' (Add a concept to a lesson), which is a clear verb+resource statement. It differentiates from sibling tools like add_lesson and update_concept by specifying the exact lesson-to-concept relationship. The scope is precise and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives contextual usage guidance: course_id is auto-derived and lesson.concept_ids is auto-updated, so the caller should not pass or manually edit. This tells the agent what to avoid. However, it does not explicitly name alternative tools or state exclusions, so it lacks the full 'when/not' explanation.

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

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

No annotations are provided, so the description carries the full burden. It discloses the content format (Markdown), title fallback logic, and fixed source value. However, it omits details like return value, error behavior, or permission requirements, leaving some transparency gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences front-load the core purpose and then provide derivations and constraints. Every clause carries information, with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a create operation with no output schema, the description covers the key inputs, the standalone scope, title behavior, and fixed source. It doesn't explain return value or edge cases, but the schema's idempotency_key description covers retry semantics, making it reasonably 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?

With 67% schema coverage, the description adds meaningful semantics: it clarifies that title is optional and auto-derived from content (frontmatter > H1 > truncated first line), and that content_md is Markdown. The idempotency_key parameter is already well-described in the schema, so no duplication is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('上架' = publish) and a specific resource ('Markdown 文档'), and explicitly states it is not attached to any course/lesson, distinguishing it from add_lesson and update_document. It also clarifies title auto-derivation and fixed source, making the tool's function unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly states the document is standalone ('不挂靠任何 course/lesson'), implying use for free-standing materials rather than course-linked lessons. It does not explicitly name alternatives or when-not-to-use, but the 'new document' and 'not attached' constraints provide clear contextual boundaries relative to sibling tools.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says "add exercises" and offers no information about side effects, idempotency (though the schema mentions idempotency_key), validation behavior, permissions, or whether existing exercises are affected. This is a significant gap for a write operation with an 8-parameter input.

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, clean sentence with no fluff or redundancy. It is front-loaded and immediately conveys the basic action, meeting the conciseness bar. It is admittedly sparse, but that issue is more directly punished in other dimensions.

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 an 8-parameter tool with no output schema, no annotations, and no return-value description, a single sentence is far from complete. The agent has no information about expected outcomes, error handling, or how this tool interacts with lesson workflows, making it difficult to invoke correctly in a real scenario.

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 description does not mention any parameters, and schema description coverage is only 50% (4 of 8 parameters have descriptions). Key parameters like prompt, order, reference_answer, and agent_skill_used are left undocumented in both the schema and the description, leaving the agent without guidance on their format or required values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description "为 lesson 添加课后习题" clearly states the action (add) and the resource (lesson), and references the concept of after-class exercises, which distinguishes it from sibling tools like add_flashcard or add_simulated_quiz. However, it is terse and does not explicitly name the object being created (e.g., an exercise entity with prompt/reference_answer), so it stops short of the most specific formulation.

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 gives no guidance on when to use this tool versus alternatives, no mention of prerequisites (e.g., lesson must exist), and no exclusions. The agent is left to infer usage from the tool name and the minimal action phrase.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, but only states that FSRS state is initialized by the server. Other important behavioral traits (e.g., idempotency behavior, plain-text rendering, concept_id existence check, grouping semantics) are left to the schema descriptions, not the tool description. This falls short of full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one short, front-loaded sentence that immediately conveys the core purpose. It is appropriately concise but lacks additional context that would make it more useful. No word is wasted, but the brevity limits its overall contribution.

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?

Despite having 6 parameters and no output schema or annotations, the description is extremely minimal. It does not explain what a flashcard is, how it relates to other entities, or what the expected result/return value is. The schema descriptions partially compensate, but the overall description is incomplete 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?

The input schema has 100% parameter description coverage, so the baseline is 3. The tool description itself adds no parameter information beyond what the schema already provides. However, the schema descriptions are quite rich, so the baseline 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 '添加一张闪卡' clearly states the action (add) and the resource (flashcard), using a specific verb+resource format that directly distinguishes it from sibling tools like update_flashcard. The added note about FSRS state initialization further clarifies the tool's scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or recommendations. Although parameter schemas include some usage hints (e.g., deck_id guidance), the tool description itself offers no such direction.

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

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

With no annotations, the description must disclose behavioral traits. It adds a specific rule about mindmap seeds: '默认不生成、例外才有', and clarifies that skipping it is not penalized ('不写不罚'). However, it does not disclose other operation behaviors such as return values, error handling, or permanent side effects, leaving partial transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a coherent single paragraph with the purpose front-loaded and the nuanced policy following. Each sentence earns its place, though a more structured bullet-point format could improve scannability. The date '2026-07-21 定' adds minor context but is not essential.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is relatively complex (9 params, nested objects, no output schema, no annotations). The description covers the core purpose and a key optional-parameter policy, but does not explain return values, error behavior, or the meaning of required fields like order and content_markdown. This leaves the description moderately complete but not fully informative.

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 description adds meaningful guidance for the modality_declarations.mindmap parameter by explaining when to configure it (only when structure clarity is needed) and that leaving it empty is acceptable. This goes beyond the schema's simple description. However, it does not clarify the semantics of several undocumented parameters like order, title, content_markdown, and estimated_minutes, so it only partially compensates for the 56% schema coverage.

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 begins with '为指定 course 添加一节 lesson', clearly stating the action (add) and target (a lesson to a specified course). It also provides usage context with 'agent 备课时用', which helps distinguish it from lesson-update tools like update_lesson.

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 phrase 'agent 备课时用' explicitly indicates when to use the tool, giving a clear usage context. It does not name alternative tools or specify when-not-to-use scenarios, but the creation-oriented context is sufficient; the mindmap policy is more about parameter selection than tool selection.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior, and it does so thoroughly. It states that teacher_note appends without replacing the body, and erratum keeps the original text while placing the patch alongside, never rewriting the lesson. This clearly communicates non-destructive side effects and the constraints on each patch kind.

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 sentence but every clause carries essential information. It front-loads the purpose, then the three laws, then the progress-check directive. There is no redundancy or filler; it is efficient and well-structured.

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?

Despite no output schema and no annotations, the description fully compensates. It covers the decision tree (unstarted/in-progress/completed), the appropriate patch kind for each state, the non-destructive behavior, and the prerequisite progress check. For a tool with six parameters and nuanced rules, this is remarkably 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 coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema by explaining when to use each kind (teacher_note vs erratum) based on lesson progress, and provides a concrete example for source_attribution. While not every parameter is elaborated, the added context for kind and source_attribution elevates the 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 clearly states the tool's function: adding a teacher note or erratum patch to a lesson. It explicitly distinguishes from the sibling tool update_lesson, noting that unstarted lessons should be updated directly rather than patched. The verb 'add' and resource 'lesson patch' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: unstarted lessons should use update_lesson, in-progress lessons only allow teacher_note, and completed lessons only allow erratum. It even instructs the agent to check lesson_progress status before deciding, naming the exact endpoint. This is exemplary usage guidance.

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

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

With no annotations, the description carries the full burden. It discloses important behaviors: idempotency via idempotency_key ('同一 key 重放此调用返回首次结果, 不重复写入'), server-side ownership validation ('服务端校验归属', '服务端验存在性+归属'), and detailed field/layout contracts (e.g., '非 root 必带 parent_id', 'links 只画跨分支联想'). This goes well beyond a basic 'creates a mindmap' statement.

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 paragraph, but every sentence and clause carries essential information. It is well-structured with a logical flow: purpose, REST equivalence, field contract, layout rules, and documentation reference. It is appropriately sized for a tool with such a complex input schema, though it could be slightly more 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?

The description thoroughly covers purpose, usage, input semantics, validation, and idempotency, which is extensive for a complex tool with a nested object. The main gap is that it does not describe the return value of a successful call (no output schema is present), though it hints at return behavior via idempotency. It also references an external tutorial, which adds completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is high (86%), the description adds significant meaning beyond the schema. It explains the '字段合同' (field contract) for nodes and links, the layout constraints (pos_x/pos_y ranges, root position), and clarifies the pair_id restriction and idempotency_key behavior. This enriches parameter understanding substantially.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: attaching an agent-generated mindmap seed to a lesson or course ('为 lesson 或 course 挂一张 agent 出的思维导图 seed'). It also distinguishes it from related tools by explaining it's a merged version of two REST calls (POST /mindmaps + POST /mindmaps/:id/associations), making it distinct from update_mindmap_seed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for use: it's for lesson preparation ('省得 agent 备课时绕 REST'), and it explains that it's a combined create-and-associate operation. However, it does not explicitly mention when not to use it or explicitly name alternative tools like update_mindmap_seed, so it lacks explicit exclusions.

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

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

With no annotations provided, the description carries the full burden and does a good job disclosing validation behavior: required existence of course_id, non-empty questions, mandatory choices for single/multi choice, reference_answer membership in choices, and multi_choice comma-separated encoding. It also clarifies grading behavior for open questions (not graded, left for self-assessment). However, it does not mention return value or explicit side effects beyond 'add'.

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 sentence containing purpose, mirroring detail, and all validation rules. Every clause carries essential information with no filler. It is efficient but could benefit from structured bullets for readability, so not a perfect 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers validation and grading behavior extensively, but lacks a return value description (no output schema) and does not explicitly state the required fields inside each question object (stem, reference_answer) beyond what the schema provides. Given the tool's nested complexity and absence of annotations, it is adequate but leaves some gaps.

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?

Given low schema description coverage (25%), the description compensates by explaining key parameters: course_id existence, questions structure and non-emptiness, choices requirement, reference_answer semantics, and question_type handling. It adds meaning beyond the bare schema, though it leaves idempotency_key and agent_skill_used to schema/other context.

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 begins with a specific verb and resource: '为指定 course 添加一份模拟卷' (add a simulated quiz for the specified course), clearly distinguishing it from siblings like add_exercise or add_document. It further defines the tool as a 1:1 mirror of a REST endpoint (POST /pairs/:pairId/simulated-quizzes), reinforcing its specific purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides constraints for use (course_id must exist, questions non-empty, specific validation rules) but does not explicitly state when to prefer this tool over alternatives or when not to use it. The '1:1 mirror' reference implies a direct mapping but offers no comparative guidance against sibling tools.

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?

Since no annotations are provided, the description carries the full burden and does an excellent job. It discloses key behaviors: removal from pending/bridge/inbox, persistence of the message, default behavior of clearing to the latest message, idempotency, and a warning that misuse is visible to the learner. This goes well beyond what annotations would typically 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 description is a single dense paragraph where every sentence contributes essential information: purpose, usage conditions, side effects, default behavior, idempotency, and a caution. It is front-loaded with the action and criteria, making it easy for an agent 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?

For a tool with two parameters, no output schema, and no annotations, this description is remarkably complete. It covers purpose, when to use, behavior, parameter defaults, and edge cases (idempotency), leaving no significant gaps for an agent to misinterpret.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers only message_id (50% coverage), while thread_id has no description. The description adds meaning by explaining that thread_id refers to the thread and that message_id defaults to the latest message. It also clarifies the effect on queues, but thread_id's format and expected values are still not explicitly detailed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool acknowledges a thread/message by removing it from pending, bridge wait, and teacher inbox while preserving the message itself. It uses a specific verb ('消账') and names the affected resources, and distinguishes itself from sibling tool adhoc_thread_get by noting that messages can be read back.

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 gives explicit conditions for when to use the tool: when the learner explicitly says no reply is needed, or when the assistant judges a response is unnecessary. It also mentions an alternative for reading back (adhoc_thread_get), but does not explicitly mention reply tools like adhoc_message_send for the opposite case, leaving a slight gap in when-not-to-use guidance.

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

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

With no annotations, the description carries the full burden. It discloses a key side effect: setting is_learning_related=true will persist a SessionEvent. It also mentions free conversation limitations, but it does not describe other behavioral traits such as deduplication via client_message_id, return values, or error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences and front-loaded with the primary purpose. Every sentence adds operational information: the thread context, free-form nature, rich content encoding, and learning-related behavior. No redundant phrases.

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 6-parameter tool with nested objects and no output schema, the description covers the core use case well: response mechanism, rich content, and learning flag. It lacks explicit alternative comparison (live vs adhoc) and details about client_message_id deduplication, but the schema compensates for parameter-level details.

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 67% (4/6 parameters have descriptions). The description adds semantic context for is_learning_related (SessionEvent) and explains the payload shorthand, but it does not elaborate on content or thread_id beyond what the schema already implies. This adds marginal value over the 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 description clearly states the tool's purpose: the agent responds to users in an AdHoc thread. It distinguishes from siblings like live_message_send by explicitly specifying the AdHoc thread context and noting that it supports free conversation not limited by move_type.

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 indicates when to use the tool (for agent responses in AdHoc threads) and provides guidance on rich content via payload and learning-related flag. However, it does not explicitly name alternatives or state when not to use it (e.g., in live sessions), so it stops short of full exclusionary guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool may create a thread ('Get-or-create'), defaults to the current pair, and changes behavior based on after_message_id, including cost implications. It does not detail return format or error cases, but the key side-effect and cost traits are disclosed.

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—two sentences—and front-loads the core purpose before diving into usage nuances. Every phrase earns its place, including the cost warning and default-behavior note. The structure is dense but 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?

Given the tool has no output schema and no annotations, the description covers the essential operational context: what it does, when to use incremental vs. full reads, and the cost trade-off. It lacks explicit return-value or error information, but for a get-or-create thread tool, the provided context is sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%, with after_message_id having a rich schema description and pair_id having none. The description compensates by explaining that after_message_id enables incremental reads and that the default pair is used, adding practical meaning to pair_id. It does not fully detail every parameter but adds significant value beyond the 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 description opens with 'Get-or-create 这个 pair 的长存 AdHoc thread', which clearly identifies the verb (get-or-create), the resource (long-lived AdHoc thread), and the scope (the pair). This distinguishes it from sibling tools like adhoc_message_send or live_wait, which focus on messaging/waiting rather than thread retrieval/creation.

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 explicitly states when to use incremental reads ('值更循环里带上你已读到的最后一条 id 只取增量') and when full reads are appropriate ('首次上任/断档补课时用'). It also warns about cost implications of full reads, giving clear practical guidance for tool selection.

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

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

No annotations are provided, so the description carries full burden. It discloses irreversibility, four validation checks (ungraded submissions, cognitive update requirement, ref_id validity, Live session receipt requirement), enum enforcement with rejection of unknown kinds, and the optional receipt with historical context. This is exceptionally transparent.

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 wall of text without clear section breaks, containing historical details (dates, retirement rationale) that are not essential for invoking the tool correctly. While every sentence carries information, the length is excessive and could be better structured with bullets or headings. It is not front-loaded with the most critical operational 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 complex tool with nested receipt objects and multiple validation rules, the description is highly complete. It covers all preconditions, error scenarios, validation logic, and even the rationale behind the enum. It notes that receipt carries closure progress, so no separate state-machine query is needed, addressing output expectations despite no output 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?

Input schema has 100% parameter description coverage, so baseline is 3. The description enriches semantics by explaining when receipt is optional, the meaning of each receipt kind, the rules for ref_id, and when no_cognitive_update_reason is needed. It adds value beyond the schema, though much detail is also embedded in the 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 description clearly states the tool's purpose: closing the lesson loop by writing a receipt and setting lesson_progress to closed. It distinguishes itself from siblings like get_lesson_closure_state (read-only status) and grade_exercise (grading) by specifying it is the terminal, irreversible action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to use: after grading and receipt delivery, with a warning that it errors if already closed. It lists preconditions (four server-side checks) and alternatives (grade_exercise for grading, record_post_lesson_evaluation for cognitive updates), and explains when receipt is mandatory (when Live lesson exists) and the escape hatch (no_cognitive_update_reason).

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

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

With no annotations, the description carries the full burden and does so excellently. It discloses strict validation behavior with structured rejection and detailed diffs (two failure types), idempotency (repeated calls return existing result without error or duplicate write), and the semantics of the completion_note as a serious testimony. It also explains the final-state nature, making the mutation's effects clear.

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 long but every sentence earns its place. It is front-loaded with the primary action, then systematically covers state distinction, note expectations, preconditions, failure modes, and idempotency. Numbered lists and clear separation of concerns make it easy to parse despite its density. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a complex mutation tool with strict preconditions, failure modes, and idempotency behavior. The description covers all these aspects, references related tools (update_contract_coverage, get_context), describes rejection response structure, and explains the repeated-call behavior. No output schema exists, so the description sufficiently explains what to expect. It is effectively complete for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers all parameters at 100%, so the baseline is 3. The description adds value by elaborating on completion_note's intent ('不是流程按钮上敷衍一句') and idempotency_key's use in retries ('网络重试/断线重连时带上同一个 key'), going beyond the schema's descriptions. However, it does not add significant new meaning for contract_id beyond the schema. Thus a 4 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 opens with a clear, specific verb+resource: '把一份合约收作结业' (close a contract as completed). It distinguishes this from sibling tools like void_contract by explaining it is the third terminal state (completed_at/completion_note) alongside established/voided, and explicitly notes it is not an override relationship. This makes the tool's purpose unambiguous and well-differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use and when-not-to-use guidance. It states preconditions required before calling (contract active, covered_course_ids non-empty, each course goal_completion_ready) and names alternative/upstream tools ('先 update_contract_coverage', '见 get_context 的 contract_progress'). It also clarifies that voided or already-terminal contracts are rejected, implicitly distinguishing from void_contract. This is comprehensive usage 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?

No annotations are provided, so the description carries full burden. It discloses critical behaviors: contract validation (must be active and same pair, else rejected), auto-merge into covered_course_ids, and the exact impact of planned_lesson_count on completion determination, including the permanent 'no later entry' consequence when null. This is rich and non-obvious.

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?

Although a single dense paragraph, every sentence adds essential context: purpose, contract linking, validation, and completion logic. It is front-loaded with the primary action and structured logically. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and no annotations, the description covers all key operational aspects: when to use, side effects, validation rules, and follow-up consequences. It is complete enough for an agent to invoke correctly without ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has moderate coverage (57%). The description adds significant meaning to contract_id (validation, auto-merge) and planned_lesson_count (completion threshold, null behavior). Other parameters like topic, description, and generated_from are not elaborated but are self-explanatory or covered by schema descriptions. The added semantics compensate for the gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states '新建一个 course' (create a new course) with added specificity about zero-material topics and no need to attach to an existing course. It distinguishes itself from sibling tools like update_contract_coverage by describing the auto-merge behavior and from add_lesson by focusing on course creation.

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?

Explicitly states when to use: '零材料启动新主题时' (when starting a new topic with zero materials). It also names an alternative: '等价紧接着调一次 update_contract_coverage' (equivalent to calling update_contract_coverage), making the choice 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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses key behavioral traits: refusal when the learner name is not registered, refusal on duplicate active pair, success makes the pair current, real pair precedence over demo, and required sequential steps (consent conversation before pairing). No annotation contradiction exists.

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 paragraph, but it is well-structured and front-loaded with purpose. Every sentence adds value, though it could be slightly trimmed. It uses emojis and section markers for readability, earning a 4.

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 tool with 7 parameters, nested objects, and no output schema, the description is remarkably complete. It covers prerequisites (name registration), pre-steps (informed consent), post-steps (read orientation recipe), edge cases (duplicate pair), and current-relationship semantics. It fully equips an agent to invoke the 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema for critical parameters: learner_display_name has a sovereignty red line, agent_provider/model/display_name are self-reported by the agent, and idempotency_key is implied for retry safety via 'same key replay'. This extra semantic weight justifies a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: to establish a new learner-agent relationship (pair). It specifies the exact resource and action, and distinguishes itself from siblings by calling itself the 'only proper door to real enrollment' and referencing when get_context reports No active pair.

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 usage guidance is provided: use this tool when get_context reports no active pair, and follow the bootstrap recipe's no-pair branch. It also states when not to use (if an active pair already exists, the tool refuses and points to the existing relationship), giving clear context and 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a compact snapshot with summarized fields (not full content), explicitly states what is NOT included ('不含全量', '不含全文'), and reveals an Etag contract that allows skipping get_learner_brief. It also describes error response with available pair list. This is substantial behavioral detail, though it doesn't mention side effects (likely none as a read).

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 long but dense and well-structured, with clear labels for each return field (active_contracts, recent_lessons, pending_pool, live_session, unread_adhoc_count, active_reminder_count) and the Etag contract. Every sentence adds operational value (what's included, what's omitted, when to skip dependent calls). It's front-loaded with the core purpose and then details the snapshot contents.

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 read-only context snapshot tool with no output schema and no annotations, the description covers: purpose, when to call, what each returned field contains, what is intentionally omitted, the etag caching behavior fallback for no activity, and error behavior. This is a complete operational contract for an agent to decide when to call this vs alternatives.

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 has one optional param pair_id with zero description coverage. The description explains pair_id's semantics: it's an optional input, defaults to current active pair, and if nonexistent returns an error with available pairs. This fully compensates for the schema gap, even though the description doesn't specify the exact format (e.g., string pattern).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it's a one-shot cold-start positioning tool for a session: '一发式冷启动定位: session 醒来先调这个, 拿到...的紧凑快照'. It specifies the resource (active pair context snapshot) and distinguishes from manually composing multiple calls (live_pending + snapshot + thread). While it doesn't name a specific sibling, the stated contrast with combining several sibling tools' outputs differentiates it.

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?

Explicitly says when to use: 'session 醒来先调这个' (call this first when session wakes). Provides a concrete exclusion: if brief_etag matches last remembered, skip get_learner_brief. Also notes pair_id defaults to current active pair, and error behavior when pair_id doesn't exist. This is strong usage guidance.

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

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

With no annotations, the description carries the full burden and delivers. It discloses that reference_answer is the confidential grading key and instructs not to leak it to learners, and that only exercises in the current pair can be read, with other/nonexistent IDs returning NOT_FOUND. These are meaningful behavioral details beyond a basic 'get'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one compound sentence but densely packs purpose, return fields, usage context, confidentiality warning, and scope constraint. It is front-loaded with the core purpose and contains no filler, though the structure is somewhat run-on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and annotations, the description provides a thorough picture: return fields are enumerated, error behavior (NOT_FOUND) is specified, and the confidentiality warning covers an important handling concern. For a simple read tool, this is 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 coverage is 100% and the parameter description already explains the ex_ prefix and the current-pair requirement. The tool description mostly restates this constraint and adds no new parameter-level meaning, so it remains at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('读回'/'read back') with the resource 'exercise' and explicitly lists the returned fields (prompt, reference_answer, expected_concepts, tags, lesson info). This clearly differentiates it from siblings like add_exercise (creating) and grade_exercise (grading).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use: '批改前先审教材用这个' (use this to fetch the problem statement and grading criteria before grading). It provides clear context, though it does not explicitly name alternatives or exclusions.

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

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

No annotations are present, so the description carries the full burden—and it excels. It discloses default/clamping behavior for limit, active-pair fallback for pair_id, redaction of forbidden hypotheses, etag caching semantics, error behavior with available pairs, and lesson_id preference with fallback. It even details the semantics of confidence_facts (pure numeric, no adjectives/percentages).

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 long but extremely dense and well-structured with labeled return sections, a 'red line' redaction note, an etag contract, and fallback logic. Each sentence adds distinct information; there is no filler or repetition. The upfront '开课前先调这个' is a high-signal opening.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description fully compensates by enumerating every return field with precise semantics, including edge cases (null confidence_facts, redacted hypotheses, lesson_id no-match fallback), error behavior, and caching. For a 3-parameter tool with no annotations and no output schema, this description is complete and self-sufficient.

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 67% (pair_id lacks description), but the description compensates fully by explaining pair_id's default (current active pair), limit's default and clamp, and lesson_id's filtering/fallback semantics. It adds behavioral meaning far beyond the schema, including which parameters are optional and their interaction with the return payload.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb-resource pairing ('读回学生模型'), states when to invoke ('开课前先调这个'), and enumerates exactly what is returned. It clearly distinguishes this from generic getters by scoping to learner_hypotheses / post_lesson_evaluations / teacher_reflections and explicitly says not to manually query tables.

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?

Explicitly states '开课前先调这个' as the primary usage context and instructs the agent to avoid manual table reads ('不用自己扒表'). It also gives conditional guidance for optional parameters (like lesson_id fallback behavior). It does not name alternative sibling tools for exclusion, but the context is strong enough to guide selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the default compact behavior, the optional full-content flag, the inclusion of content_chars and an excerpt in compact mode, the error behavior (NOT_FOUND for non-current pairs), and the potentially long content_markdown. This is far more transparent than typical tool descriptions.

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 paragraph that front-loads the core purpose and then efficiently covers behavior, parameters, and constraints. Every sentence adds detail: token economy, error case, and pair restriction. There is no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given only 2 parameters, no output schema, and no annotations, the description is remarkably complete. It explains the default response shape, the optional field, the error condition, and the intended use cases. An agent can decide whether to invoke the tool and with what arguments without needing additional context.

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 100% for both parameters, so the baseline is 3. The description adds significant value beyond the schema: it explains the default value of include_content (false), the token-economy rationale, specific use cases for true, and the constraint that lesson_id must belong to the current pair. This elevates the score above baseline.

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 '读回一节课' (read back a lesson), specifying a clear verb and resource. It enumerates exactly what is returned (title, structure, publish status, body), and distinguishes itself from siblings like get_lesson_closure_state by focusing on the lesson's full content and metadata.

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 explicitly states when to use the default compact mode (token economy) and when to pass include_content=true, citing concrete use cases such as grading prep and resume-teaching cold start. It also clarifies the limitation that only the current pair's lessons are accessible. It does not name alternative tools for explicit comparison, but the guidance is clear enough for an agent to decide.

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 提供只读/破坏性提示，描述承担全部责任。它明确声明'只读、不改动任何状态'，并详细披露了 state 的语义陷阱（state 是首个缺口而非已达成项）、Live 相关字段出现的条件、incorrect_review_signal 不参与阻塞关课等，远超最低要求，行为边界非常透明。

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?

信息密度很高，每句话都有实质内容，并且把最重要的一句话（'关课前先调我'）放在开头。但整体是一大段中文长句堆叠，没有使用列表或分段来分隔返回字段、状态语义、读法警示等不同主题，快速扫读时略显费力，因此扣 1 分。

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?

无输出 schema，描述必须承担解释返回值的责任。它完整覆盖了返回对象的所有字段（lesson_id、state、completed[]、missing[]、next_required_action、incorrect_review_signal），并解释了每个字段的取值含义、边界条件和 null 情况，对预检工具来说是闭环的。

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 对单个参数 lesson_id 已有 100% 覆盖（'必须是已存在的 lesson id，server 会查存在性'），描述没有额外补充参数格式或约束。虽然描述中提到了预填 id 列表包含 lesson_id，但并未直接增强参数语义，因此给予高 schema 覆盖下的基线 3 分。

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?

描述开门见山指出工具是关课前的预检调用（'关课前先调我'），并说明其作用是把顺序、缺口、下一步和 id 串好。同时明确与兄弟工具 close_lesson_loop 的关系：复用同一份事实装配但不改动状态，清晰区别于写操作工具，目的明确且具有辨识度。

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?

明确给出使用时机：关课前先调用；同时通过'只读'和'复用 close_lesson_loop 同一份事实装配'隐含了与写操作工具的替代关系，并说明 closed 状态时 next_required_action 为 null，帮助调用方理解何时无需再操作。虽未逐一列举其他替代工具，但对本工具的核心使用场景和边界交代充分。

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?

Despite no annotations, the description thoroughly discloses behavior: it returns specified fields (including enum status, nullable confidence, exercise chain), and it states the crucial constraint that only the current pair's submission works—other or nonexistent submission_ids return NOT_FOUND. This goes well beyond a bare 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?

Although a single long sentence, the description is densely packed and well-organized with slashes, enumerations, and an em-dash. Every clause adds functional information—return fields, statuses, nullability, scoping, and error behavior—with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description fully compensates: it lists all return fields, specifies enum values, notes nullable confidence, explains the exercise chain, and discloses the NOT_FOUND behavior. It also positions the tool in a larger grading workflow, making it complete for its simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully describes the single parameter (submission_id, required, sub_ prefix, must belong to current pair). The tool description essentially restates the 'current pair' constraint without adding new semantic nuance. With 100% schema coverage, 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 clearly states the action ('读回' / read back) and resource (a learner's submission), listing the exact fields returned. It also distinguishes itself from siblings by framing it as the read-back side for grading and review, separate from get_exercise and grade_exercise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit context for when to use: it is for '批改与复盘' (grading and review), and it instructs to pair with get_exercise to fetch reference_answer then grade_exercise. It doesn't list exclusions but clearly frames the workflow and complementary tools.

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

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

With no annotations provided, the description carries the full burden and delivers rich detail: server statelessness (consumer must track cursor), deterministic item IDs, sorting rules, empty-array return, and non-blocking open_feedback behavior. This exceeds typical transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: purpose, input semantics, sources, output fields, sorting, and special segment. Front-loaded with the primary action and cleanly structured into logical sections.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the absence of an output schema, the description thoroughly explains return fields, sources, cursor behavior, pagination state, and the open_feedback section. It is fully actionable for an agent without external context.

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 only 50%; the description adds helpful semantics for 'since' (default full list, ISO cursor, stateless behavior) but provides no explanation for 'pair_id' beyond indicating it is optional. A partial compensation, leaving a notable 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 clearly states this is an 'incremental teacher todo list' and explicitly differentiates from sibling tools by saying 'look here first instead of piecing together live_pending + submissions + adhoc'.

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 explicitly says to use this tool 'when waking up' and names the alternatives (live_pending, submissions, adhoc). It also directs open_feedback handling to update_feedback_status, providing clear guidance on when to use it versus a related tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It extensively details side effects and conditions: the wrong-answer flow includes concept_refs and human_note in the receipt, regrading requires explicit regrade: true to avoid CONFLICT, and successful regrading appends previous_score/previous_feedback to a new exercise.graded event. These disclosures go far beyond the schema and provide substantial transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and covers multiple aspects (trigger, wrong-answer flow, regrade rules, event traces) in three sentences. Every sentence adds substantive value, though the structure is slightly run-on and could be broken into clearer points. It remains informative without being excessive.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and lack of output schema, the description provides a good overview of the main workflows: initial grading after async event, wrong-answer specifics, regrade requirements, and event trace behavior. However, it omits details about the correct-answer path (what happens if score is correct) and the full response structure. Despite these gaps, it covers the most critical aspects for an agent to invoke the 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?

Schema coverage is 60%, with score, regrade, and idempotency_key already documented in the schema. The description adds marginal nuance by mentioning the CONFLICT rejection for regrade without the flag, but does not clarify feedback or submission_id beyond their names. Since the schema already covers most parameter semantics, the description adds minimal additional value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: '批改一条 ExerciseSubmission' (grade an ExerciseSubmission), with a specific verb and resource. It also differentiates from siblings by describing the asynchronous trigger (pair://exercises/pending) and the specific grading workflow, which is distinct from other tools like add_exercise or get_submission.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: it should be called after receiving the async event pair://exercises/pending, and explicitly explains the regrade workflow (must pass regrade: true for already graded submissions, otherwise CONFLICT). However, it does not explicitly name alternative tools for related tasks, so it falls short of a perfect 5.

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

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

With no annotations, the description carries full behavioral disclosure. It explains key nuances: ttl_seconds semantics, the 'waiting does not burn model turns' contract, and the retirement of context_status. However, it does not disclose return values, error handling, or whether the call is idempotent, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but each sentence carries relevant information, covering purpose, warnings, and contracts. It is front-loaded with the core purpose and then elaborates on nuances. Slightly longer than strictly necessary, but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers many contextual aspects: purpose, ttl semantics, usage alternatives, and legacy deprecation. However, it lacks details on pair_id, return values, and mechanics of how the heartbeat is recorded or used. Given the absence of an output schema and annotations, these gaps affect completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%: ttl_seconds has a schema description, pair_id does not. The description adds meaningful semantics for ttl_seconds by clarifying it is an online window, not a polling interval, but it never explains pair_id. Since pair_id is undocumented in both schema and description, the compensation is incomplete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as an 'Agent 端 keep-alive' and defines the online window via ttl_seconds. It distinguishes itself from related tools by mentioning live_wait's auto-heartbeat and the retired context_status parameter, though it does not name 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?

The description provides explicit usage guidance: it warns that ttl_seconds is an online determination window, NOT a polling interval, and explicitly forbids model-layer polling. It suggests alternatives (watchdog script, live_wait, custom listeners) and points to a recipe, making the when and when-not usage 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?

No annotations are provided, so the description carries the burden. It discloses that non-FRAME openings are structurally rejected, enforces first-move sequencing, and defines response_kind/content rules. It stops short of describing return/error format or session lifecycle, but it gives substantial 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, with each sentence covering a useful rule. It is slightly long due to multiple conditional constraints, and the parenthetical '(EXPLAIN)' is ambiguous, but there is no wasted wording.

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 an 8-parameter tool with no annotations and no output schema, the description misses key aspects: payload is an object but its purpose is never explained, source_id/source_type are unmentioned, and error/return behavior is vague ('结构化拒绝' not elaborated). The main Teaching Move flow is well covered, but the overall contract is incomplete.

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 only 38%, but the description compensates by constraining move_type (FRAME-first), response_kind (text/none rules), and content (300-char limit, single responsibility). It does not explain payload, source_id, or source_type, so it is not fully comprehensive, but key parameters gain significant meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with '追加一条 Teaching Move (Live Teaching 结构化教学)', clearly identifying the verb (append) and resource (structured Teaching Move). It also implicitly distinguishes itself from adhoc_message_send, and the closing sentence explicitly names the sibling for free-form chat.

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 detailed usage rules: first message must be FRAME, alternatives for free conversation/Q&A are explicitly delegated to adhoc_message_send. It also states constraints (ASK/PROBE/CHALLENGE require text response_kind; REFLECT requires none; content <=300; one move = one thing).

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

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

With no annotations provided, the description carries full behavioral burden and does so thoroughly. It discloses anti-abuse 'teeth': 6 empty calls in 90 seconds attach a warning field, 12 reject the query, and real pending data resets the counter. It also clarifies that agent_owes_move items appear only in snapshots and not in the wait event stream, plus defines what the snapshot contains.

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 information-rich, but it front-loads a warning rather than the core purpose and mixes multiple concerns: anti-abuse rules, contract v3, priority ordering, and pending_reason taxonomy. While every sentence has value, the structure could be tighter and more purpose-first.

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?

This tool has no output schema and no annotations, yet the description covers the snapshot content, sorting priority, non-blocking nature, anti-abuse thresholds, fallback pair behavior, and event-stream semantics for agent_owes_move. It even points to recipe://live-teaching for further contract details, making it complete for a complex tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, pair_id, has zero schema description coverage, but the description compensates by stating that omitting it uses the current active pair. It does not specify the expected format or how 'active pair' is resolved, but for a single optional parameter this is sufficient practical guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'live_pending 只做一件事: 拍一张 Live Teaching pending queue 的快照' (live_pending only does one thing: takes a snapshot of the Live Teaching pending queue), including priority ordering and non-blocking semantics. It also clearly distinguishes the tool from sibling live_wait and watchdog scripts, making its unique role unmistakable.

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 gives explicit when-to-use guidance: it warns '这不是值更工具' (this is not the duty tool), instructs the agent to use live_wait or scripts/live-watch.py for duty monitoring, and declares repeated empty calls a contract violation. It also explains fallback behavior when pair_id is omitted, using the current active pair.

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

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

With no annotations, the description carries the full burden. It discloses idempotency, a key behavioral trait for retries, and mentions the two termination contexts. However, it does not explain side effects (e.g., whether session data is invalidated) or any permissions required, leaving some transparency gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, with only two clauses, and every word contributes meaning. It front-loads the primary action and adds idempotency as essential context. This is exemplary conciseness without losing informational value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, and the description covers its core purpose and idempotency. However, it does not describe the return value or error cases, and it omits any prerequisites (e.g., session must be active). Given the presence of sibling lifecycle tools, a fuller context would help agents avoid misuse.

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 50%; only idempotency_key has a schema description, while session_id does not. The tool description does not clarify session_id's semantics or format. Since the description does not compensate for the missing schema description, parameter understanding is incomplete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states '中止 session' (terminate session), identifying the verb and resource. It also mentions two specific trigger scenarios (learner early end or system timeout), which distinguishes it from siblings like live_session_complete, which likely handles normal completion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: use when a session ends prematurely or times out. It does not explicitly name alternatives or exclusions, but the trigger scenarios imply when this tool is appropriate relative to completion tools.

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

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

With no annotations provided, the description fully discloses behavioral traits: idempotency ('session 已是 completed 时重复调用不再改 session...回执...'), status transitions ('status → completed, awaiting_role → none, ended_at 只在首次完成时打'), evaluation overwrite semantics ('已有场评时不覆盖'), and conflict behavior. It even explains historical rule changes (2026-07-26 口径收窄), ensuring the agent knows exactly what side effects to expect.

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, single-paragraph wall of text, but it is front-loaded with the core purpose and every sentence carries critical operational information (required fields, learner visibility, ID policy, idempotency, preconditions, gate). It could be improved with bullets or section headers, but there is little fluff; the historical note about 2026-07-26 is slightly meta but clarifies a rule change, so a 4 is appropriate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (stateful session completion, optional nested evaluation, idempotency, hard preconditions) and lack of both annotations and an output schema, the description is remarkably complete. It covers success behavior, failure modes (CONFLICT), idempotent replay details, side effects on session fields, and how to verify prerequisites. The description fully equips an agent to invoke the tool correctly and know what to expect.

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 high (83%), so the baseline is 3, but the description adds significant parameter-level meaning beyond the schema: it emphasizes that all three REFLECT fields are mandatory and rejection occurs if any is missing, clarifies that internal IDs must never appear in the text and only belong in evaluation.evidence_refs, and explains the evaluation object's relationship to record_live_evaluation. This goes beyond the schema's descriptions, warranting a 4.

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 '收课——Live 收尾的一次写作动作' (closing a session—a single writing action at the end of Live), which clearly identifies the verb (complete/finalize), resource (live session), and purpose. It also distinguishes from siblings by noting 'cancel 不受此门 (取消≠收官)' and explicitly equates the optional evaluation to a separate call to record_live_evaluation, making the tool's unique role unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: it lists prerequisites ('调用前确认——学习者最后一题已单独判过...且她已明确表态收课'), a hard gate ('必须已有学习者收课宣告...未宣告时本工具 CONFLICT 拒收官'), and exclusion ('cancel 不受此门'). It also tells the agent what to do if the learner has only verbally ended (guide them to press the bell), and references alternative tools like record_live_evaluation.

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

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

There are no annotations, so the description carries the burden of behavioral disclosure. It transparently states that this is a read operation returning the full session, all moves, and all responses. It does not cover potential performance costs or explicit side-effect disclaimers, but the read-only nature is implied and the return scope is clear.

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 extremely concise: one main clause stating the read scope and a short usage directive. Every word earns its place, with no redundancy or 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 simple single-parameter getter, the description covers purpose, return contents, and usage timing. It could add more about output structure or performance implications, but the tool is simple enough that the description is largely 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?

The schema has one required string parameter (session_id) with no description, and the description does not mention session_id at all or add any format/constraint context. Since schema coverage is 0%, the description should compensate but does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb '读' (read) with an explicit resource 'LiveSession 全貌' and enumerates the scope: session + all moves + all responses. This differentiates it from sibling tools like live_session_start, live_session_complete, and live_snapshot_get_latest.

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?

'决定下一步前必读' explicitly tells the agent when to use this tool: before deciding the next step in a LiveSession. It does not name alternatives or exclusions, but the usage context 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?

With no annotations, the description takes on the full burden of behavioral disclosure. It adds important details: default context_type 'lesson', and that an existing active room leads to joining rather than starting anew (joined_existing). However, it does not mention return values, success/error outcomes, or permission requirements, leaving some transparency gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense sentence that packs several critical facts: the entry point change, schema default, and existing-session behavior. It is front-loaded with the core action and avoids filler, though the date and narrative could be more compressed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the key scenario and the joined_existing edge case, which is valuable. However, without an output schema, it leaves return behavior undefined, and several parameters (goal, context_preview) remain unexplained. The tool is usable but not fully self-contained for an agent.

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 only 40% (context_type and idempotency_key have descriptions). The description adds meaning by stating context_type defaults to 'lesson', but it does not clarify the roles of goal, context_id, or context_preview. This is a partial, not full, compensation for the low schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states its purpose: starting a new live session, and clearly identifies the actor (teacher/agent side) and the context (learner-side button retired). It distinguishes itself from sibling tools like live_session_complete/cancel/get by focusing on the 'start' behavior, including the edge case of joining an existing session.

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 clear when-to-use guidance: it is the main entry point for opening a class from the teacher/agent side, with the learner web button retired. It also outlines behavior when an active classroom already exists. It does not explicitly list alternatives, but the context strongly implies when this tool is appropriate.

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

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

No annotations are provided, so the description bears the full burden. It indicates a read operation ('读') and adds context about the recovery workflow, but does not mention error handling, permissions, or the return format. This is adequate but not rich.

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 very concise, with two short sentences front-loading the core purpose and a key usage note. Every word 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?

For a simple tool with one parameter and no output schema, the description gives the core purpose and a usage context that implies the return value (the snapshot). It leaves a little to be desired about the exact response structure, but is sufficiently complete for its simplicity.

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. The description only mentions 'session' in passing and does not explain the session_id parameter's meaning or expected value beyond the obvious from the name, providing no additional semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('读' / read) and the resource ('session 最近一份 mid-lesson snapshot' / the most recent mid-lesson snapshot of a session). It also distinguishes from siblings like live_snapshot_write by focusing on retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage context: it is the first step in compact recovery, with the formula 'snapshot + 之后的 moves' defining its role. It doesn't explicitly list alternatives or exclusions, but the recovery workflow guidance is specific and useful.

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

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

With no annotations, the description must carry the behavioral burden. It states that this is a checkpoint write and that it enables later retrieval without re-reading moves, but it does not disclose overwrite behavior, session state requirements, or failure semantics. The idempotency behavior is only in the parameter schema, not the main description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured: purpose, frequency, retrieval, and benefit each get a short sentence. No fluff, and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description provides sufficient context for selecting and invoking the tool: it explains purpose, usage frequency, and how to retrieve the snapshot. It does not explain return values, but no output schema exists, and for a write operation this is less critical. Overall, it is quite 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 high (83%), so the schema already documents most parameters. The tool description adds the 'every 3 turns' hint for after_turn_n, but overall contributes little beyond schema, matching the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: 'flush a rolling checkpoint' in a Live Teaching session. It distinguishes this tool from its retrieval sibling by explicitly referencing live_snapshot_get_latest, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: recommended every 3 turns ('建议每 3 轮写一次') and indicates retrieval via live_snapshot_get_latest after compaction, contrasting with re-reading all moves. It lacks explicit when-not-to-use scenarios, but the guidance is strong.

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

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

With no annotations provided, the description bears the full burden of disclosure, and it delivers richly. It discloses the blocking wait duration (~50s), the silent wait and immediate return behavior, the timeout semantics (timeout=true, events=[]), heartbeat side-effects (ttl 60), persistent cursor semantics for consumer_id, and the contract version protocol. No behavioral surprise is left undocumented.

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 continuous dense paragraph, which makes scanning harder, but nearly every sentence carries crucial information. It is front-loaded with the core wait semantics and then systematically covers timeout, heartbeat, cursor, and contract version. A bulleted list would improve structure, but given the high information density, it remains appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 optional parameters, no annotations, no output schema), the description is remarkably complete: it explains blocking behavior, timeout handling, heartbeat, cursor persistence, contract version negotiation, and the relationship to alternative tooling. The main omissions are the exact shape of returned events and the purpose of pair_id, but the description covers the core usage contract thoroughly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents 4 of 5 parameters (80% coverage), but the description adds significant behavioral meaning beyond those schema notes. For example, it explains the 'since' parameter as a confirmation to advance the cursor, and describes the auto-resume behavior for consumer_id. However, pair_id remains completely undocumented in both schema and description, which is a notable 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 clearly states a specific verb and resource: '阻塞等待下一个 Live Teaching / AdHoc 事件' (block waiting for the next Live Teaching/AdHoc event). It explicitly differentiates itself from live_pending by framing this as waiting rather than polling, and it names the sibling tool ('比反复调用 live_pending 省 token'), which removes any ambiguity about its role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool versus alternatives, stating that it is more token-efficient than repeatedly calling live_pending and that it shares logic with GET /bridge/wait. It also tells the user not to call live_pending on timeout ('直接再挂一次即可, 不必先调 live_pending 探路'), which is a clear exclusion. This is exemplary usage guidance.

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

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

With no annotations, the description carries the full burden. It discloses the workflow prerequisite, the output status (proposed/waiting for signature), and the important scoping rule (only Class A/B, not C). It also explains when cadence and source_material should be included. However, it omits mention of idempotency behavior and return format, though idempotency_key is present in 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?

The description is long but appropriately structured for a complex tool. It front-loads the prerequisite (read skill first) and organizes the class hierarchy clearly. Some redundancy exists in the cadence and source_material elaborations, but the length is justified by the need to prevent misuse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, no output schema, and no annotations, the description is fairly complete: it covers prerequisites, workflow, parameter scoping, and post-submission behavior (user sees draft card and can adjust Class B/cadence). It does not address return values or error cases, but provides enough context for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83% (>80%), so baseline is 3. The description adds meaning by grouping parameters into Class A/B/C and specifying under which conditions cadence and source_material should be provided (e.g., if discussed in conversation, or if the learner brings their own book). This supplements the schema's per-parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states that the tool submits a TeachingContract draft to LS with setup_status: proposed (waiting for learner signature), and defines the exact scope: only Class A + Class B, plus cadence/source_material exceptions. This clearly distinguishes it from sibling tools like update_contract_cadence or void_contract.

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-to-use: after the contracting dialogue is finished, and requires reading skill intake/contract-establish first. It also gives when-not-to-use: Class C is not accepted and is instead handled via the signing desk form, while cadence/source_material are exceptions if discussed. This is strong, actionable guidance.

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

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

With no annotations, the description carries the transparency burden. It discloses key behaviors: server-side validation, red-light blocking on FAIL, and setting published_at on PASS. It also notes yellow-light manual review does not block. While it doesn't cover all edge cases (e.g., idempotency replay), the core state transition and failure condition are explicit.

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?

Two dense sentences efficiently convey the workflow: input, validation gate, and outcome branches. The use of domain-specific metaphors (红灯清单, 翻牌) is succinct but may be opaque to some agents. No wasted words; structure is front-loaded with the action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main scenario well for a 2-parameter, no-output-schema tool: publish gates, validation outcomes, and side effects. It lacks explicit details on PASS return values and broader error handling, but the core state transition and blocking condition are sufficiently specified. Adequate for agent decision-making.

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 100%, so both lesson_id and idempotency_key are already well-documented. The tool description adds context that lessons originate from add_lesson as drafts, which helps interpret lesson_id's semantics, but doesn't significantly enhance understanding beyond the schema. 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 clearly states the tool's action: publishing a lesson to learners (上架). It distinguishes from siblings by explicitly referencing add_lesson's draft state and positioning this as the Publish Gate. The verb+resource+scope is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage after add_lesson, as it explains the draft-to-publish workflow. It mentions verify_prep's same validation logic, providing context but not explicit alternatives or exclusions. The guidance is clear enough for an agent to decide when to call, though not as prescriptive as naming 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?

With no annotations, the description carries the full burden. It discloses the verbatim text requirement, server-side validation for anchors, non-validation of source_message_ref, the mandatory confirmation receipt, the non-blocking 'soft teeth' behavior, and idempotent boundary updates with delayed effect. This is rich behavioral transparency beyond basic read/write.

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 long but information-dense; each clause adds behavioral or contextual detail. It front-loads the core purpose in the first sentence, though the single-paragraph structure could be more scannable. For a 9-parameter tool, the length is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's role, usage scenarios, parameter semantics, edge cases (idempotency, boundary updates), and postconditions (receipt, soft teeth). It even explains why boundary updates are folded into this tool and the effective timing. Complete for a complex tool with no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters, but the description adds crucial semantics: text must be verbatim original words, anchors are validated for existence and pair ownership, source_message_ref is unvalidated, boundary_update's idempotency and atomity with text, and idempotency_key's purpose. This significantly augments the schema descriptions.

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 '现场反馈笔' and immediately clarifies it records learner issues/ideas from daily messages, with no dedicated UI. It clearly distinguishes from sibling recording tools by specifying the subject (learner feedback) and the unique 'every input box is an entry' behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use: when the learner raises a product/teaching issue or idea in daily messages, and also when a boundary change is requested. It doesn't name alternative tools but provides clear contextual triggers, and mentions that boundary changes must go through this tool rather than being assumed silently.

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

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

With no annotations provided, the description carries the full behavioral burden and does so richly: forbidden-domain writes silently return an explanation without error, rejected/frozen/confirmed sovereignty rules are spelled out, revise leaves expired traces, and stale hypotheses are only hinted at without auto-retirement. This goes far beyond minimal mutation disclosure.

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 with the core purpose, and every sentence carries necessary policy or behavioral information. However, it is a single long unbroken paragraph mixing creation rules, prohibitions, lifecycle semantics, and sovereignty; bullet or section structure would improve scanability. Only a minor structural deduction.

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?

Without an output schema or annotations, the description still covers purpose, creation timing, prohibited domains, lifecycle behavior, sovereignty rules, stale status handling, and even the no-write response behavior. It provides enough context for an agent to select and correctly invoke the tool in complex scenarios.

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?

Despite 100% schema coverage, the description adds substantial meaning beyond the schema: pairing hypothesis_id with action switches to lifecycle mode, giving hypothesis_id alone errors, domain triggers a forbidden-registry check, evidence_event_ids append to the existing evidence ledger, and action-specific parameter requirements are clarified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with '写一条 LearnerHypothesis' (write a LearnerHypothesis), specifying the exact verb and resource, then immediately describes lifecycle variants (create/reinforce/revise/retire). It explicitly distinguishes itself from reflect_on_teaching by stating that confidence-level judgments belong to that tool, not this one.

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-to-use rules ('3 课之后才允许首次写'), when-not-to-use rules (domain hits forbidden registry, confidence judgments), and names the alternative tool (reflect_on_teaching). It also provides decision guidance for lifecycle actions: '有证据就 reinforce, 被推翻就 revise/retire'.

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

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

With no annotations, the description carries the full burden and discloses key behaviors: idempotent return of existing record on duplicate live_session_id, no overwrite, prerequisite of completed status, and that the receipt includes closure progress. It also informs that agent_observation is visible to learners in a collapsible section, which is critical contextual behavior beyond 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?

The description is dense but every sentence adds value: main gate, exception path, prerequisites, idempotency, field guidance, and receipt behavior. It is front-loaded with the core purpose and uses parentheticals to clarify distinctions. No filler or redundant phrases.

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 no output schema, the description covers the return aspect by stating the receipt brings closure progress. It also covers prerequisites, idempotency semantics, and field-level constraints. The tool is complex (8 params, sibling names), and the description provides sufficient context for correct invocation without needing to guess.

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 63%, and the description compensates richly. It explains agent_observation must be a short verdict, not a transcript, and that internal IDs should go to evidence_refs, not the text. It also adds meaning to idempotency_key (use for retries), learner_note (learner-visible, language from locale), and evidence_refs (server-validated against same pair). These explanations go well beyond the 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 description uses a specific verb+resource: '写一条 LiveSessionEvaluation' (write a LiveSessionEvaluation), and clearly distinguishes it from record_post_lesson_evaluation by stating this is for a single live_session, not course-level. It also explains the relationship to live_session_complete as the main gate, making the tool's specific role unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: as a supplementary channel when the evaluation was missed during closing. It also names the primary flow (live_session_complete with optional evaluation), provides prerequisites (live_session exists with status=completed), and explains idempotent behavior on collision. This is clear, actionable guidance with exclusions.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it reveals update-in-place behavior on duplicate (pair_id, lesson_id), rejection of all-default payloads, the three-part structure of agent_observation, the three-channel rule for internal IDs (only in evidence_refs), and receipt behavior including update-not-create and progress. No contradictions with annotations because none are present.

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 paragraph of operational rules with no filler; every clause contributes to correct usage. It could be more scannable with bullet points, but the natural-language flow remains efficient and information-dense, earning a 4.

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 tool with 13 parameters, nested objects, uniqueness constraints, and detailed validation rules, the description covers purpose, timing, content restrictions (one-decision principle, no restating exercises), rejection criteria, idempotency, update semantics, and receipt behavior. It also references the spec for threshold details, making it effectively complete for an agent to select and 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?

The description adds significant meaning beyond the schema by explaining the three-channel system (learner_note, evidence_refs, agent_observation), the rule that agent_observation must avoid machine terms and internal IDs, and the rejection condition covering seven parameters. However, several numeric fields (e.g., concepts_touched, duration_minutes) still lack explicit semantic clarification, so 4 rather than 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 clearly states '写一条 PostLessonEvaluation' (write one PostLessonEvaluation) and specifies it is a pure fact-layer record written at the end of every lesson. It differentiates from siblings like record_live_evaluation and grade_exercise by explicitly stating exercise judgments belong to grade_exercise and that live comparisons form part of agent_observation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit timing ('每节课末尾都写' — write at the end of every lesson), a directive to avoid restating exercise judgments (pointing to grade_exercise), and a reference to the three-lesson threshold rule in TEACHING-SPEC §4.3. It also states the receipt carries closed-loop progress so state-machine queries are unnecessary, implicitly guiding against using sibling tools.

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

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

With no annotations provided, the description carries full responsibility and does so extensively. It discloses the silent UI (return only counts, no UI entry), weather_expires_at expiry and the prohibition on learner-profile writes, server-side anchor validation and rejection of non-pair ids, anchor inference fallback with warnings for unanchored reflections, and the closure-progress inclusion in the receipt.

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 flawlessly structured: it front-loads the core action and then details the attribution skeleton, anchor validation, inference logic, and return-receipt behavior. Every sentence contributes a distinct fact about behavior or constraints, with no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a highly complex tool with no annotations and no output schema, the description is remarkably complete. It covers the return value (one-line count plus receipt fields like created_refs.anchored_lesson_id and human_note), failure modes (unanchored reflection, pair mismatch), inference precedence order, and closure-progress semantics, leaving very few ambiguities for an agent.

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 56%, and while the description reinforces key parameter relationships (e.g., action_link type-to-ref_id mapping, weather_expires_at requirement), it adds little beyond what the schema's descriptions already state. Several required parameters without schema descriptions (method, rationale, next_action) remain unexplained in both places, making this a minimal-viable rather than compensatory 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 explicitly states the tool's purpose ('写一份 TeacherReflection') with clear scope (per-lesson, starting from lesson 3). However, it does not explicitly distinguish itself from sibling tools like record_post_lesson_evaluation or close_lesson_loop, relying instead on its unique attribution-skeleton requirements to imply 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?

The description gives clear context: use at the end of each lesson, attach lesson_id, and it explicitly says the receipt includes closure progress so '不用另查状态机' (no need to query the state machine separately), which is a when-not guidance. It does not name alternative tools for similar actions like recording evaluations, limiting 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?

No annotations are provided, so the description bears full behavioral disclosure burden. It only lists updatable fields and says 'revise', but fails to disclose partial-update semantics (merge vs replace), error handling for nonexistent concepts, validation results (e.g., flashcard existence), idempotency behavior (though the schema hints at it), or any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with the verb and resource up front, followed by a compact field list. Every element contributes meaning, with no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a mutation tool with no annotations and no output schema, yet the description provides minimal context. It omits return behavior, error semantics, partial-update rules, prerequisites (e.g., concept must exist), and any guidance on idempotency_key usage, making it incomplete for safe autonomous invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides descriptions for source_refs (format), flashcard_ids (existence check), and idempotency_key (retry behavior), covering about 50% of parameters. The description adds a list of updatable fields, which is slightly redundant with the schema's properties but clarifies that concept_id and idempotency_key are not content fields to be modified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb '修订' (revise) and targets the 'concept' resource, explicitly listing the four updatable fields (name / short_definition / source_refs / flashcard_ids). The word '已有' (existing) clearly distinguishes this from sibling tool add_concept, which creates new concepts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool ('revise existing concept') but provides no explicit alternatives or exclusions. It does not state 'use add_concept for new concepts' or warn against misuse, leaving usage context mostly implicit.

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

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

With no annotations, the description carries the full transparency burden and excels. It discloses critical behavioral traits: full replacement semantics (not merging), lack of revision/history table, automatic updated_at stamping, and that reminders are only stored, not sent. These go far beyond any 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?

The description is dense but well-structured: purpose first, then cadence shape, then critical behavioral warnings. Every sentence carries vital information—no filler, no repetition of schema defaults. It is front-loaded with the most important scoping statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (nested object, full replacement, idempotency, no history), the description is remarkably complete. It explains the full-replacement danger, the historical anomaly of the version column, the automatic timestamp behavior, and the reminder non-delivery. No output schema exists, but for an update tool the description provides sufficient context without needing to detail return values.

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?

Even though schema coverage is 100%, the description adds substantial semantic meaning beyond the schema: full-replacement behavior (clear risk of losing unspecified fields), auto_duty's explicit-consent requirement and default false, prep_rhythm's meaning, and the automatic updated_at insertion. It also references skill docs for deeper semantics.

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 precise verb+resource: '只改一份已签合同的 cadence(节奏条款), 不动其他任何条款、不必重签.' This clearly distinguishes it from siblings like update_contract_coverage and void_contract, and explains the tool's raison d'être.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use (modify cadence on an existing signed contract) and when not to (do not change other clauses, no need to re-sign). It also explains the economic rationale—'改约成本必须低于立约'—and implies the alternative of re-signing, making the usage context unmistakable.

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

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

With no annotations provided, the description carries the full burden and thoroughly discloses behavioral traits: dedupe semantics, validation rejection (not silent ignore) for invalid or non-pair course IDs, and the terminal state rule for completed contracts. It leaves little ambiguity about edge cases and side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense paragraph, but every clause earns its place: purpose, validation rules, dedupe behavior, and terminal-state restriction. There is no filler or redundant wording, making it efficient for an agent 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?

For a mutation tool with no annotations and no output schema, the description covers purpose, constraints, validation, dedupe, and lifecycle restrictions, which is strong. It lacks an explicit description of the return value or success/failure response, but the behavioral specification is otherwise 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?

The schema provides 100% parameter descriptions, so the baseline is 3. The description adds meaningful semantics by stating that at least one of add_course_ids or remove_course_ids must be a non-empty array, and explains dedupe/validation behavior beyond what the schema covers.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb '修改' (modify) with the resource 'covered_course_ids 覆盖单' and clarifies it is the list of actually taught courses, not the license scope. This clearly distinguishes it from sibling tools like update_contract_cadence or complete_contract.

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 explicitly states that completed contracts (completed_at non-null) are rejected and directs users to open a new contract to continue teaching, providing an exclusion and alternative behavior. It implies usage for active contracts, though it does not name sibling tools directly.

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?

无任何注解，描述承担了完整的行为披露责任。它披露了非常关键的非显然副作用：正文变化时自动重新普查全部划线，失联的进孤儿区，且绝不静默删行。这种透明度远超普通更新操作，但未提及权限要求、返回结果或并发处理，因此不是满分。

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?

两句话，第一句直接说明用途，第二句解释重要的行为副作用，没有冗余内容。信息密度高且高效。

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?

工具是修改操作，无输出 schema，描述提供了核心用法和关键副作用，引用了外部 brief 作为补充。但缺少返回/成功标准、失败处理或并发控制的上下文。对于这个复杂度而言已经足够，但仍有提升空间。

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 描述覆盖率仅 25%（仅 idempotency_key 有描述），描述中隐含 title 和 content_md 是可更新字段，但未明确说明 document_id 的含义或 idempotency_key 的使用时机。由于描述只部分补偿了 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?

描述明确说明该工具用于更新已有文档的标题和/或正文，并指明是“报告修订版”，动词和资源都很具体。与同级别的 add_document（新增）、update_lesson（更新课程）等兄弟工具区分明确。

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?

描述隐含使用场景：修改已有文档，而非新建文档，与 add_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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals important traits: addressed/declined are terminal and cannot be changed, declined requires a note (validation rule), and the 'soft teeth' effect—advancing status is not enforced by other tools but leaving feedback open keeps it visible in the inbox. This goes well beyond a simple status update.

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 core lifecycle. Every sentence contributes meaningful information—state transitions, terminality, note requirement, and downstream impact—with no fluff or repetition. The 'soft teeth' metaphor is efficient and memorable.

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 there is no output schema or annotations, the description covers the essential context: purpose, behavioral constraints, validation rules, and relationship to other tools. It is comprehensive for a status-update tool, though it does not mention the return value or error conditions, which are less critical for understanding usage.

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 100%, so parameters are already well-described. The description adds value by explaining the status lifecycle, terminal states, and the note requirement for declined status, which enriches understanding of the 'status' and 'note' parameters beyond their schema descriptions. It does not need to repeat parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: advancing a learner feedback through its lifecycle (open → acknowledged → addressed/declined). It specifies the resource (learner feedback) and the action (advance lifecycle state), and distinguishes itself from siblings like record_learner_feedback (creation) and get_teacher_inbox (viewing) by emphasizing status transitions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context on when to use the tool: when you need to advance feedback status, and explains the consequences of not using it (open feedback stays glowing in get_teacher_inbox, but no hard gates are blocked). It also references related tools (close_lesson_loop, get_teacher_inbox), giving clear situational guidance, though it does not explicitly name alternative tools.

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

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

With no annotations, the description carries the full burden and excels: it discloses pure patch semantics (only given fields changed), no revision snapshot, preservation of FSRS scheduling state and paused flag, no progress reset, and NOT_FOUND for other/nonexistent pairs. This gives the agent a complete picture of the tool's side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single block of several sentences, but each sentence provides a distinct piece of information: purpose, behavior, constraints, and usage context. It is front-loaded and not wastefully verbose, though it is longer than strictly necessary, earning a 4 rather than 5.

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 no annotations and no output schema, the description comprehensively covers purpose, parameter semantics, behavioral constraints, error condition (NOT_FOUND), and usage timing. The only gap is no mention of return values, but this is not critical for an update tool and the description is otherwise thorough.

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 100%, so baseline is 3. The description adds value by clarifying patch semantics — only provided fields are modified — and referencing update_concept precedent, which goes beyond the schema's simple 'optional' labels. This meaningfully aids parameter handling.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it revises existing flashcard content fields (front/back/deck_id) using pure patch semantics. It clearly differentiates from add_flashcard and delete-recreate workflows, and references update_concept as a precedent, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: after verification/review catches card face issues, and explicitly advises against delete-and-rebuild, noting that rebuilding loses scheduling progress. It also states the constraint that only the current pair's cards can be modified, setting clear boundaries.

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

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

With no annotations provided, the description carries the full burden. It transparently discloses side effects (snapshot, revision increment), strict rejection without revision_reason, mindmap behavior (optional, not generated by default), and the teaching/technical distinction with default and learner-facing implications. This is highly informative.

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 paragraph but front-loads the purpose and provides essential behavioral details. It is somewhat run-on, yet every sentence is informative and there is no fluff. It could benefit from clearer segmentation, but remains effective and concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (10 params, nested objects, no output schema), the description covers the core mutation flow, mandatory fields, and nuanced revision_kind semantics. It does not mention return values or some straightforward params (title, lesson_id), but those are self-evident and partially covered by schema descriptions. Overall, it is sufficiently complete for correct usage.

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 60%, not low enough to demand full compensation. The description adds meaningful guidance for revision_kind (with the teaching/technical heuristic) and modality_declarations.mindmap (same as add_lesson, no penalty), but it does not enrich other parameters like idempotency_key or evidence beyond what the schema already provides.

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 begins with '修订已有 lesson' (revise an existing lesson), clearly identifying the verb and resource. It goes further to describe the revision workflow (snapshot to lesson_revisions, apply patch, increment revision), which distinguishes it from sibling tools like add_lesson and add_lesson_patch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for existing lessons and mandates revision_reason, but it does not explicitly state when to prefer this tool over add_lesson_patch or other revision-related siblings. It lacks an explicit when-not-to-use or alternative comparison, though the revision semantics provide some context.

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

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

With no annotations, the description carries full burden. It discloses key non-obvious behaviors: the source=agent permission check, the dual-column write ('写入会同时同步 content 与 agent_seed_snapshot 两列'), and the historical bug motivating this behavior ('只改 content 会让 Clear & redo...诈尸'). This is exactly the kind of context an agent needs to avoid a subtle failure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences pack purpose, restrictions, validation, and a behavioral caveat. Each sentence earns its place, though the '诈尸' zombie metaphor is colorful and may slightly obscure clarity. Overall, efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (nested object, 3 params, no annotations, no output schema), the description covers purpose, usage restrictions, validation linkage, and a critical write-behavior pitfall. It also mentions the permission error type. This is sufficient for an agent to invoke correctly without additional context.

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 100%, so baseline is 3. The description adds value beyond the schema by pointing to the full field contract in add_mindmap_seed ('字段合同见 add_mindmap_seed 说明') and a complete tutorial. This cross-reference helps the agent understand content structure more deeply, exceeding what the schema's brief descriptions provide.

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 '修复/迭代你自己播种的课程脑图' (fix/iterate your own seeded course mindmap), clearly stating the action and resource. It distinguishes from sibling add_mindmap_seed by focusing on updating an existing agent-owned mindmap, and further differentiates scope by specifying source=agent.

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?

Explicitly states when to use: only for source=agent mindmaps. Provides a when-not case: '学习者自己长出来的图不许 agent 动, 会打 PERMISSION' (learner-grown graphs not allowed, will get PERMISSION). Also references add_mindmap_seed as the validation contract, implying the alternative for creation.

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

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

No annotations are provided, so the description carries full burden. It transparently discloses read-only behavior ('只读, 零写库'), validation error codes (VALIDATION, NOT_FOUND), return status levels (PASS/PASS_WITH_WARNINGS/FAIL), course-level aggregation details, and the CLI equivalence. All key behaviors are covered.

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 every sentence adds value. It is front-loaded with the primary use case, then systematically covers safety, parameters, output modes, and equivalence. No redundancy or 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?

Given the absence of annotations and output schema, the description provides complete context: usage scenarios, parameter selection rules, error codes, compact vs verbose output shapes, and CLI correspondence. It fully compensates for missing structured metadata.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes all 3 parameters with 100% coverage, but the description adds critical semantics: the mutual exclusivity rule (both/neither → VALIDATION), the behavior for each value (single-lesson report vs course-level summary), and ordering by lessons.order. This goes well beyond the 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 description clearly states the tool's purpose: a final verification step for lesson preparation ('备课收尾必调'), checking cross-item consistency across textbooks, flashcards, exercises, mind maps, and concepts. It distinguishes itself from sibling tools by being read-only and validation-focused, contrasting with the write-oriented 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?

Explicitly says when to use: before delivery ('交付前跑一遍'). It clarifies the lesson_id vs course_id selection rule and the distinction from write operations ('写入门禁看单发, 本工具看全家福'). This gives clear context and differentiates from 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?

With no annotations provided, the description carries full burden and fully delivers. It specifies the exact side effects: 'active=false, voided_at=now(), void_reason=...' and that the contract exits current contract selection. It discloses idempotency behavior, stating repeated calls return the voided state without error, second write, or overwriting the original void_reason. This is comprehensive behavioral disclosure.

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 front-loaded with the most critical prerequisite (consent) and then compactly covers the effect, idempotency, and relationship to the read model. Every sentence earns its place; there is no fluff or repetition of schema content.

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 no annotations and no output schema, the description covers prerequisites, exact side effects, idempotency, and even references the implementation file (lib/currentContract.ts) for affected read paths. It is complete enough for an agent to correctly select and invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and each parameter already has detailed semantics (e.g., reason is the original text to show, learner_consent must be the learner's verbatim words, idempotency_key for retries). The description adds workflow context but does not materially extend the per-parameter meaning beyond the schema, so a baseline score of 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 uses the specific verb '作废合约' (void contract) and clearly defines the resource as a teaching contract. It distinguishes the behavior from deletion by stating '作废不是删除——合约行原样保留' (void is not delete—the contract row is preserved), which sets it apart from a destructive delete and implies it is a state transition. This is clear and differentiates from sibling tools like complete_contract in effect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides strong usage context: it mandates that the reason must be shown to the learner and consent obtained before calling, and states that unauthorized calls are a violation ('未经同意调用属违纪'). It also clarifies that this is not a deletion operation. However, it does not explicitly name alternative tools (e.g., complete_contract) or state when to prefer voiding over completing, so it lacks an explicit exclusion for those alternatives.

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