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

No annotations provided, so description must cover behavioral traits. It mentions the Snowflake ID truncation issue and that explain content is self-contained (D2). However, it does not disclose whether the tool is destructive, idempotent, or requires specific permissions. Score 3.

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 concise sentences plus a note. No wasted words, front-loaded with purpose. Efficient and clear. Score 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 6 parameters, 0% schema coverage, and no annotations, the description covers the main modes and return format but omits seq and node_id semantics. It is adequate but not fully complete. Score 3.

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 description should compensate. It explains the kind parameter and associated parameters (question_id, explain_text, explain_title). However, it does not explain seq or node_id, leaving gaps. Score 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?

The description clearly states '给节点加一个内容项' (add a content item to a node), and distinguishes between question and explain kinds. It differentiates from sibling 'add_book_node' which adds a node itself. Score 4 because it is specific but could be more explicit about the overall 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?

The description explains when to use each kind (question vs explain) and warns about question_id formatting. It does not explicitly state when not to use or alternatives, but provides sufficient context for the two modes. Score 4.

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, description discloses node addition behavior, parent_id handling, kp_id's knowledge graph role, name visibility on exam paper and forbidden words, and return type. Missing error conditions or side effects, but covers key behaviors well.

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 with front-loaded action, examples, constraints, and return value. No filler, each sentence adds unique value despite informal notation.

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

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

Covers purpose, key parameters, constraints, and return type. Lacks explanation of seq and error handling, but overall sufficient for a moderately complex tool given output schema exists.

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

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

Schema coverage is 0%, so description compensates partially. Explains node_type (examples), parent_id (default root), kp_id (optional KG anchor), and name (constraints). Does not explain book_id (required) or seq (default 0), leaving 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?

Description clearly states '给书加一个目录节点' (add a TOC node to a book), specifies node_type examples, and distinguishes from siblings like add_book_item and get_book_structure via context of adding nodes to the book hierarchy.

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 practical usage tips (parent_id for root, kp_id optional, name constraints) but lacks explicit when-to-use or when-not-to-use compared to siblings. No mention of prerequisites or 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 fully discloses behavioral traits: archiving is a soft delete that removes from scheduling picker but retains history, archives cancel future sessions, and unarchiving does not restore cancelled sessions. The return format is also given.

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 well-structured with bullet points and bold text, but it is slightly verbose. It effectively communicates key points without 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?

Given the output schema exists and the description covers all main aspects (soft delete, cancellation side effect, unarchive limitations), it is complete for a simple two-parameter 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?

Though schema coverage is 0%, the description explains target_id as a snowflake string ID and archived boolean with default True and meanings for True/False, adding 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 clearly states the tool archives/unarchives teaching targets (students/classes) as a soft delete, with a distinct purpose from siblings like create_teach_target or list_teach_targets.

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 explains when to archive (to soft delete) and the side effects (cancels future sessions, unarchiving does not restore). However, it doesn't explicitly contrast with alternative tools like hard delete or other target management operations.

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 discloses critical behavioral traits: it only updates a single column (book_node_ids) using partial updateById, explicitly warns about a historical bug where full row upsert erased paper_slots, and details the return format for each action. This exceeds minimal expectations.

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 well-structured with a clear purpose, context, warning, parameter list, and return format. It is front-loaded but slightly verbose due to the historical warning; still every sentence adds 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?

Given the complexity and presence of an output schema, the description covers main use cases and return types. It does not mention error handling or invalid inputs, but is sufficient for an AI 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?

With 0% schema description coverage, the description fully compensates by detailing each parameter: lesson_id (string), node_id (string, ignored for action=materials), action (default 'bind', values explained). It adds meaning beyond the bare schema structure.

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: binding, unbinding, or querying book chapter nodes to lesson material positions. It distinguishes from the sibling tool bind_special_to_lesson by noting that both are material slots and their union determines lesson readiness.

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 explains the three actions (bind, unbind, materials) and their effects. It implicitly guides usage by noting the relationship with bind_special_to_lesson, but does not explicitly state when to choose this tool over alternatives or provide 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 provided, so description fully carries the burden. It details behaviors: return structure, side effects of unbind (resets manual_ready), parameter constraints, and the fact that it never makes items public. All important 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?

Well-structured with sections and bullet points, but slightly verbose with emojis and repeated emphasis. However, for the complexity (3 actions, conditional params), the length is justified and information is 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 tool complexity, output schema existence, and lack of annotations, the description covers input, output, behavior, and context. It contrasts with relevant siblings and states constraints (no public). Complete and sufficient for agent 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 0%, meaning no descriptions in schema. The description compensates fully by explaining each parameter: lesson_id required, slot_seq conditionally required, action enum with three values and their conditions, paper_id for bind, and ready for manual_ready with default. Adds critical context beyond schema structure.

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: managing post-creation binding, unbinding, and marking ready for lesson paper slots. It distinguishes from the main path (create_paper/compose_paper) which handles automatic binding during 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 describes when to use this tool (after creation) and when to use other tools (during creation). Also warns about no public ability, providing 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 fully discloses critical behavioral traits: it only updates a single column (special_ids) via partial update, never performs full-row upsert, and references a historical bug. This clearly informs the agent of the mutation's scope and safety.

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 concise yet comprehensive, structured with a main purpose statement, a historical note, a parameter list, and return shapes. Every sentence adds value without 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?

Given the tool's moderate complexity (3 parameters, multiple actions, output schema exists), the description covers all necessary aspects: actions, parameters, return values, and crucial behavioral constraints. It is complete and leaves no 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 input schema has 0% parameter descriptions, so the description entirely compensates. It explains each parameter (lesson_id, special_id, action) and notes that special_id is ignored for action=materials. It also details the return format for each action, adding significant meaning 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: to bind, unbind, or check bound specials to a lesson material slot. It specifies the resource (lesson material slot) and distinguishes between three distinct actions, making the purpose very 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 explains when to use each action (bind, unbind, materials) and provides a historical caution against full-row upsert. However, it does not explicitly compare with sibling tools like bind_book_node_to_lesson, so the agent must infer from the tool name and context which 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?

Without annotations, the description fully discloses behavior: the tool no longer performs any operation and only returns a retirement guide. It also mentions PDF export is handled externally.

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 well-structured with a prominent deprecation warning, but includes detailed workflow explanation that could be shortened. Still, it is relatively concise and informative.

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?

Essential deprecation and alternatives are covered, but parameter semantics are missing, and output (retirement guide) is not described. For a deprecated tool this may be sufficient, but gaps remain.

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 3 parameters with 0% description coverage, and the description does not explain their purpose or usage. Since the tool is deprecated, parameters may be irrelevant, but no semantics are provided.

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 is deprecated and only returns a retirement guide, which is a specific verb and resource. It also distinguishes from siblings by directing to new workflow (compose_paper, create_paper, bind_paper_slot).

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 the tool should not be used for its original purpose, provides detailed alternative workflow using compose_paper, create_paper, bind_paper_slot, and references get_role_manual for 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 fully discloses behavioral traits: it creates a real paper (真落库), assigns ownership, and avoids false success by returning {ok:false, reason} on failure. It also notes that lesson preparation papers are private and never set public.

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 concise yet comprehensive, using clear sections and symbols (🔴) to highlight important constraints. Every sentence adds value without 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?

Given the tool's complexity and the presence of an output schema, the description covers all necessary aspects: input semantics, optional parameters, behavior, return format, and error handling. It is complete for an agent to use 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, explaining the outline structure, the role of subjectId, the optional lesson_id/slot_seq pair binding, and error scenarios. This compensates for the schema's lack of description 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 the tool's purpose: composing a paper deterministically from the real question bank according to an outline and storing it. It specifies the resource (biz_paper) and ownership (current teacher). This distinguishes it from siblings like create_paper or compose_special.

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 (e.g., outline-based composition, optional binding to lesson slots) and notes that subjectId must come from list_kg_tree. However, it does not explicitly exclude alternatives or state when not to use it.

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 that source books and the question bank are not modified, explains the effect of missing secHint (creates new section), and specifies error conditions for empty picks or not logged in. It does not cover authentication requirements or rate limits, but these are typical and somewhat assumed.

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 well-structured: a one-sentence summary, then detailed explanation of the special's structure, parameter descriptions, and return values. It is slightly verbose but each sentence adds value. Could be tightened slightly, but overall 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 complexity (4 parameters, picks as array of objects) and presence of output schema (described in text), the description covers key aspects: creation process, parameter details, return values including skipped items. It lacks mention of prerequisites like login status beyond the error case, but is otherwise comprehensive.

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 input schema, which has 0% coverage. It explains the special naming constraint (clean knowledge name, no internal terms), details the picks structure with subfields (questionId/nodeId, secHint, overrideJson), and notes optional grade/subject_id. This compensates fully for the lack of 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 clearly defines the tool's purpose: building a 'special' document by selecting materials across multiple books and batch-picking questions into blocks. It specifies the structure (block → tier → question) and explicitly distinguishes from papers, which is a key sibling differentiator.

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 explains that the tool is used for creating specials (non-papers) with cross-book selection, and notes that picking occurs within a block framework. It does not explicitly list when not to use it, but the context (e.g., 'non-paper') and sibling tools (like compose_paper) provide implicit 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 full burden. It discloses a ~12s execution time, explains the override/inference behavior, and describes the return structure including a fallback case. This provides good transparency about the tool's 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?

The description is moderately concise, front-loading the purpose and using a list for parameters. It packs essential information without excessive verbosity, though the mixed Chinese/English may slightly reduce readability.

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

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

The description covers input parameters, output structure, performance, and fallback behavior. It is complete for a tool that generates figure specs, though it could mention prerequisites or side effects.

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

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

Schema coverage is 0%, so the description must compensate. It explains 'item_id' as a sequence string and 'dsl' as an optional override for redrawing. This adds significant meaning beyond the bare 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 it composes a figure for a variant question, producing a JSXGraph DSL. It specifies the output and mentions the client-side rendering. However, it does not explicitly differentiate from sibling tools like 'render_shuzimi_figure', which may have overlapping functionality.

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 explains the behavior of the 'dsl' parameter and general workflow but does not provide explicit guidance on when to use this tool versus alternatives or when not to use it.

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 provided. Description mentions execution time (~3s) and return values (ok, thread_id, status:'ready', mother_card). It does not disclose mutability, permissions, or potential side effects, but the described action (confirming and backfilling) implies mutation.

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 concise sentences followed by parameter and return info. Purpose is front-loaded, no extraneous words, and the structure aids quick scanning.

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 presence of an output schema and the straightforward workflow, the description covers the essential flow. It lacks details on error handling or type constraints, but the context is sufficient for an AI agent to use 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?

Input schema lacks parameter descriptions (0% coverage). Description compensates by explaining both parameters: thread_id comes from make_variants, chapter_id is selected from kg_candidates. This provides essential context beyond the raw 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?

Description clearly states the tool's purpose: confirm the chapter belonging to a motif, as part of a workflow after make_variants. It distinguishes from siblings by specifying its role in the 'need_confirm' branch and linking to subsequent generate_variants call.

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?

Describes when to use: after make_variants returns a 'need_confirm' branch. It also provides the next step (call generate_variants). No explicit when-not-to-use or alternatives, but the workflow context is clear enough.

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 fully discloses behavior: deterministic XML parsing, no OCR, output structure (text, paras, text_path, images with rid and local_path), and error handling for true .doc files. It explains the output format and next steps thoroughly.

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 well-structured and informative, starting with purpose, then output, next steps, parameters, and return value. However, it is somewhat lengthy; a minor trimming could improve conciseness without losing clarity.

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 presence of an output schema (as indicated in context signals), the description still provides a comprehensive overview of input, output, edge cases, and workflow. It covers all necessary information for an agent to use 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?

The description compensates for 0% schema coverage by explaining doc_path as the absolute path to the file and batch as a prefix for image filenames and text file name, defaulting to the document filename stem. This adds significant meaning beyond the input 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 it converts Word documents (.docx or disguised .doc) to structured text and an image list, specifying the method (XML parsing, not OCR). It mentions math formulas to LaTeX and image placeholders, effectively distinguishing it from siblings like convert_pdf and convert_lecture_docx.

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 guidance on next steps: feed text to parse_paper_text and images to upload_image. It also handles the true .doc case with an error message. However, it does not explicitly state when not to use this tool or compare it to alternatives, though the context implies the specific use case for Word documents.

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 comprehensive behavioral transparency. It explains the deterministic nature, no login, no storage, faithful conversion details (formatting retention, table backgrounds, image handling, EMU to px conversion, EMF/WMF limitation). It also outlines the return structures for each mode, including the deterministic_hint for assist mode.

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 about 600 characters and contains all necessary information, but it is somewhat verbose and uses a mixed format of bullet points and paragraphs. The main purpose is front-loaded, but the detailed explanation could be more organized. Still, it is efficient relative to the complexity of the tool.

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

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

Given the tool's complexity (multiple modes, multiple output structures, dependencies on other tools like upload_image and save_lecture_frag), the description is remarkably complete. It covers both return types, explains the deterministic_hint, and mentions integration points. The output schema exists, so return values are documented elsewhere, but the description adds necessary context 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 coverage is 0%, so the description must add meaning for all 5 parameters, and it does. It explains docx_path as absolute path, course_subject_id as source for KG targets, book_id with default 'CC7S', batch as output prefix defaulting to filename stem, and mode with three options and their contexts. This far exceeds the bare 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 converts a lecture docx into Tiptap content, KG knowledge points, and image list. It specifies deterministic, zero-login, zero-storage behavior. The multiple modes (assist, auto, cuicui) are explained with their intended use cases, 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 explicitly states when to use each mode: default assist for understanding-based mapping, auto only when H3 headings match KG knowledge points (cleaned source). It also provides alternatives for image handling (use upload_image and save_lecture_frag) and clarifies that the tool itself does not upload images. This gives clear guidance on when to use this tool versus others.

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 fully carries the burden. It discloses non-OCR deterministic behavior, warns about text layer unreliability, and briefly describes return format. No mention of auth or side effects, but unlikely needed for a conversion tool.

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

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

The description is extremely concise: two short paragraphs, first states purpose and key caveat, second lists parameters and return format. Every sentence is informative, with no fluff.

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

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

Given the presence of an output schema (not shown), the description need not detail returns but still gives format. It covers parameters, behavioral nuance (text layer unreliable), and use case context. Complete for a well-defined conversion tool.

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

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

Schema description coverage is 0%, but the description explains every parameter: pdf_path (absolute path), batch (prefix for filenames), dpi (rendering resolution, 170 recommended), max_pages (limit, 0=all). This adds essential meaning beyond defaults and types.

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 converts PDF to per-page images and detects text layer, using deterministic pymupdf (not OCR). It is distinguished from sibling convert_doc by specifying it's for multi-modal problem solving (拆题).

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: for problem solving, use page images directly (text layer unreliable); text layer is only auxiliary for locating problem numbers or pure text questions. It could explicitly mention alternatives like convert_doc, but the 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 fully details behavioral traits: book_type is not validated, registered values listed, registration process for new types, return format, special type excluded from bookshelf, and exclusion of import. No contradictions.

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

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

Purpose is front-loaded, but the description is a single dense paragraph. It contains necessary details but could benefit from bullet points or clearer separation of return info and next steps.

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 output schema exists (return {ok, book_id(str)}), the description covers purpose, key parameter behavior, and post-usage guidance. Missing explanations for grade, edition, and subject_id, but overall sufficient for a creation tool with subsequent steps.

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

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

Schema coverage is 0% and description only adds meaning for book_type (enumerated values, registration). Other parameters (grade, title, edition, subject_id) lack any explanation. Baseline 3 is appropriate as description partially compensates.

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 it creates a new empty book (新建一本空书) and distinguishes from siblings by noting that subsequent steps require add_book_node/add_book_item or import. The verb 'create' and resource 'book' are specific.

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 explains what to do after using this tool (use add_book_node/add_book_item or import) and warns about registering new book types. However, it does not explicitly state when NOT to use this tool versus 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 provided, so the description carries full burden. It discloses that the paper belongs to the current teacher, creates sections and associations, and optionally binds to a lesson slot with constraints (both lesson_id and slot_seq required). It also mentions that bound papers are private and never set-public, and returns success/error.

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 well-structured with a clear main purpose sentence, followed by usage context and parameter details. It uses bold for emphasis and lists parameters. It is slightly lengthy but efficient, with every sentence providing 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?

Given the tool's complexity (5 parameters, 2 required, optional binding), the description covers the full workflow: prerequisite (questions ingested), parameter constraints, behavioral side effects (private paper), and return format. It addresses all necessary context 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?

Despite 0% schema description coverage, the description explains each parameter meaningfully: name (1-200 chars), question_ids (order-sensitive, at least 1), paper_category_id (optional), lesson_id/slot_seq (must coexist, binding semantics). It adds constraints and usage beyond the schema's basic types.

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: assembling a paper from question IDs, maintaining order, and associating it with the current teacher. It specifies the resource and verb distinctly, differentiating from siblings like 'compose_paper' or 'update_paper'.

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 explains when to use: after questions are ingested, for full paper entry. It also details optional lesson slot binding, clarifying when it becomes a preparation paper. It does not explicitly state when not to use, but the 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?

Without annotations, the description carries the full burden. It details the return format ({ok, id}), explains grade_year derivation logic, and mentions server-side normalization of subject/edition. However, it omits error conditions, idempotency, and authentication requirements, which are important but not 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 long and detailed, mixing Chinese and English, which may reduce clarity. While it is front-loaded with purpose, the level of detail could be streamlined. The bullet points help structure, but some redundancy exists.

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 9 parameters (2 required) and no annotations, the description covers most aspects: all parameters explained, behavior documented, and nested object defined. Missing elements include potential errors, side effects, and confirmation of output schema details, but overall adequate.

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

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

With 0% schema coverage, the description fully compensates by explaining each parameter's meaning, valid values (e.g., grade_no range, textbook_edition codes), and for profile, providing the complete JSON structure. This adds significant value beyond the raw 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: creating a teaching target (student or class) with a specific verb ('create') and resource ('teach_target'). It distinguishes from siblings like update_teach_target and archive_target by focusing on 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 implies usage for creating targets that will be referenced later in scheduling and lesson planning, but it does not explicitly state when to use this tool versus alternatives (e.g., update or archive). No exclusions or prerequisites are provided.

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

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

With no annotations, the description fully discloses behavior: dry_run returns a list without modifying data, confirm triggers backup and deletion of all related rows, logs audit, lists blocking conditions, and requires string IDs. It also states the deletion is irreversible.

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 with information but uses symbols and Chinese punctuation. It is front-loaded with key points but could be more structured. Still, every sentence adds 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?

Given the complexity (4 parameters, output schema present), the description covers deletion behavior, conditions, limits, irreversibility, backup, and audit. It is sufficiently complete for correct tool 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 description coverage is 0%, so the description must compensate. It explains confirm (default false), mentions backup_path, and implies question_ids as targets. However, reason and backup_dir parameters are not explicitly explained, leaving some ambiguity.

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

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

The description states '安全删题（只能删散题）' meaning safe deletion of standalone questions, clearly identifying the verb and resource. It distinguishes from sibling tools by specifying the scope (only standalone questions) and no other deletion tool exists among 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?

Provides explicit when-to-use (deleting standalone questions) and when-not-to-use (blocked by various conditions). Explains dry_run mode for preview vs confirm for actual deletion, and mentions single limit of 500. Also notes that deletion is irreversible and recommends dry_run first.

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?

Without annotations, description carries full burden. It reveals key behaviors: zero LLM involvement, only patches passed fields, marks manual edit state, returns a snapshot. Missing details on overwrite vs merge and permissions, but sufficient for safe invocation in most contexts.

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?

Description is brief with one-line purpose, bulleted parameters, return spec, and follow-up advice. No wasted words, information is front-loaded and 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?

Given 3 parameters and no output schema provided in input, description covers all necessary aspects: behavior, parameter details, return structure, and post-edit action. Adequate for an agent to use 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 0%, so description must compensate. It explains thread_id, item_id as string, and patch with fields stem?, answer?, analyze? (mapping analyze to solution field). Clarifies that None keys are unchanged. Adds meaning beyond bare 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?

Description states '手动编辑某道变式（零 LLM，只 patch 传入字段）→ 标手动编辑态。' which clearly identifies the verb (manually edit), resource (variant), and specific scope (no LLM, only patch fields, marks manual state). This distinguishes it from siblings like generate_variants or verify_variant.

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?

Description includes '改后建议重跑 verify_variant' providing a post-edit recommendation. While it doesn't explicitly contrast with alternative tools, the context implies use for manual tweaks after generation. No exclusion criteria, but the guidance is clear enough.

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 explains the batch combination and file marker usage, but does not disclose side effects, authorization needs, or error handling.

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 concise and front-loads the purpose with a clear label. However, it uses unstructured symbols and could be more formally 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?

For a tool with an output schema implied by the description, it covers input, output, and usage context. Missing details on error cases or preconditions, but adequate for its complexity.

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

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

Schema coverage is 0%, so no parameter descriptions in schema. The description explains batch_key's default behavior, but target_id is not described beyond being required.

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 it exports a batch of feedback sheets for a student as one long image, and explicitly distinguishes from the single-sheet export ('不用单张'). The return fields are listed.

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 specifies the tool is for sending to parents ('发家长用'), and notes that omitting batch_key fetches the latest batch. However, it does not explicitly state when not to use or list alternative tools from siblings.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool exports a PNG to local machine and returns a file_marker that must be copied exactly. While it doesn't explicitly state it's read-only, the export nature implies no destructive side effects. However, it could be more explicit about permissions 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 fairly concise but includes necessary details. It uses emojis and bullet points for structure, making it scannable. However, it could be slightly shorter; the file_marker instruction could be integrated more cleanly.

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 only one parameter and an output schema exists (though not shown), the description covers the essential usage context and post-export steps. It mentions the output fields but not all. The missing details about parameter meaning and potential error cases prevent a higher score.

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

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

The schema has 0% coverage for descriptions (no description in schema). The only parameter is sheet_id, and the description merely says '参数 sheet_id 字符串传' (pass as string). It does not explain what sheet_id represents (e.g., which feedback sheet ID) or how to obtain it. This is minimal value added beyond the schema type.

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 exports a single feedback sheet as a parent-version PNG and downloads it locally. It specifies the output structure {ok, local_path, file_marker, ...}. It also distinguishes itself from the sibling tool export_feedback_batch_png by emphasizing it's for single sheets only.

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 (for viewing a single section) and when not to (regular parent scenarios should use export_feedback_batch_png). It also provides post-export instructions about the file_marker, guiding the agent on how to include it in the response.

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

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

The description discloses key behavioral traits: side effect of incrementing an 'used_count' counter on each item (irreversible), and specifics about page content (stars, analysis, no internal terms). This goes beyond what annotations would provide, and since no annotations exist, the description fully bears the burden.

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 well-structured with sections, bullet points, and clear explanations. It is somewhat long but every sentence adds value. Minor redundancy could be trimmed, but overall it is 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's complexity (4 parameters, side effects, output schema), the description is complete. It covers purpose, parameters, side effects, return format, and edge cases (empty special). No gaps identified.

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

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

The input schema has 0% description coverage, so the description fully compensates by explaining each parameter in detail (special_id, papers, with_analysis, with_stars) including defaults and behavior. This adds significant meaning beyond the raw 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: export a special (a set of questions) into question and answer PDFs. It uses a specific verb ('导出') and resource ('专项'), distinguishing it from sibling tools like 'compose_special' or 'bind_special_to_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 description explains what the tool does but does not explicitly state when to use it versus alternatives. There is no guidance on prerequisites or when not to use it. Usage is implied by the tool's purpose.

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?

Although no annotations are present, the description discloses that the tool never throws exceptions and degrades to markdown block on failure, and mentions the return structure. This is adequate for a formatting tool but could be more explicit about idempotency or 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 concise (5 sentences) and front-loaded with the core purpose. Every sentence adds value without fluff, though it could be slightly more organized for readability.

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

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

Given the tool's complexity, the description covers purpose, input rules, parameter semantics, return format, and integration with ingest_question. It does not include examples or edge cases, but is mostly complete for a formatting tool with an 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?

With 0% schema description coverage, the description fully compensates by explaining the meaning of question_type (with a dictionary reference), the condition for options (non-empty only for multiple choice), and the expected markdown content for stem, adding 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 clearly states the tool converts natural markdown stem and options array into blockJson for unified rendering across clients, with specific details on input content rules. It distinguishes itself from sibling ingest_question by explaining the output is to be fed to that tool.

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

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

The description provides clear context on when to use (formatting questions before ingestion) and guides the AI on minimal content to produce (markdown with sub-questions, images, LaTeX, etc.). It does not explicitly mention alternatives or when not to use, but the context is sufficient for a specialized formatting 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?

Discloses key behavioral traits: deterministic generation via seed, cross-group deduplication, difficulty levels, and that fill_rows flag affects output count. No annotations provided, so description carries full burden and meets it well.

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?

Well-structured: starts with clear purpose, differentiates from sibling, notes important safety info, then details parameters. Every sentence adds value without redundancy. Efficient use of space.

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 3 parameters and no annotations, description covers all necessary context: return structure, parameter constraints, and special cases like level applicability. Output schema not provided but return object is described.

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?

Explains each parameter beyond schema: e.g., type must come from list_calc_types, level is basic/advanced with specific applicability, label is internal only, and fill_rows default False behavior. Adds context not in 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?

Description clearly states the tool outputs calculation data without rendering PDF, contrasting with sibling generate_calc_paper. It specifies the output format {q,a} for custom layout, making its purpose distinct 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?

Explicitly states when to use this tool vs generate_calc_paper: '不出 PDF、直接返回题面与答案，排版归 agent'. Also warns against manual verification due to automatic answer computation.

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 adequately covers behavioral details: deterministic seeding, constraint handling (carrying, division, fractions), fill_rows behavior, answer sheet toggle, and group labeling restrictions. It lacks explicit permission or side-effect information, but the generation nature implies safe operation.

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

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

The description is verbose but structured with bullet points and emojis for readability. It front-loads the core purpose and then details parameters. Some repetition and informal formatting slightly reduce conciseness, but it remains efficient for the complexity.

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 details, the description covers all necessary aspects: input parameters, return format, constraints, and behavioral expectations. It provides sufficient context for correct invocation, even including a note for a 2026-07-19 specification.

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 provides extensive parameter explanations beyond the schema, including defaults, valid values (e.g., type must be from list_calc_types), and nuanced behaviors (e.g., fill_rows rounding, with_answer default false for oral arithmetic). This fully compensates for the 0% schema description 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 the tool generates a calculation paper PDF ('一键生成计算题卷') and specifies it's a deterministic program (not LLM), and distinguishes the default behavior for oral arithmetic (no answer sheet). It includes the output format and usage constraints, 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 includes some usage guidance, such as referencing list_calc_types for valid types and noting default behaviors. However, it does not explicitly differentiate from sibling tools like generate_calc_items or compose_paper, nor does it state prerequisites or when not to use this tool.

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

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

The description discloses key behaviors: occasional empty first attempt due to opus, automatic retry up to 2 times, and fallback to ok:false with engine response. Since no annotations are provided, the description carries full burden and does it well.

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 and each sentence adds value, though the warning about empty generation could be slightly more integrated. Overall well-structured but not maximally 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 presence of an output schema, the description's detailed return list is redundant but not harmful. It covers parameters, behavior, and return adequately for the tool's complexity.

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

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

Schema description coverage is 0%, so the description fully compensates. It explains thread_id as the session id after make_variants/confirm, and auto_verify in detail including its effect and default behavior. Adds significant meaning beyond the raw 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 it triggers variant generation and retrieves question sets. It distinguishes from siblings like make_variants, verify_variant, etc., by specifying it is a continuation of start_variants.

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 make_variants/confirm via thread_id, but does not explicitly state when to use this tool versus siblings or provide when-not conditions. Guidelines are implied but not explicit.

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

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

No annotations are provided, so the description carries the burden. It partially discloses behavior by detailing the return structure and special handling of override and kind=explain, but it does not explicitly state that this is a read-only operation or mention authorization needs.

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

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

The description is concise and front-loaded with the purpose, followed by a structured representation of the return type. Every sentence adds value, and there is no extraneous information.

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 of the tool (returning a nested tree), the description provides a fairly complete output schema, but it lacks explanation of the input parameter and behavioral context like error handling. Since an output schema exists, the burden is reduced, but gaps remain.

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

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

Schema description coverage is 0%, and the description does not clarify the book_id parameter beyond its name. There is no explanation of its format, how to obtain it, or constraints, leaving the agent with no additional 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?

The description clearly states that the tool returns the full book structure tree including the table of contents and content items for rendering. This distinguishes it from sibling tools like list_books or add_book_node, which have different purposes.

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

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

There is no explicit guidance on when to use this tool versus alternatives, nor are there any exclusions or prerequisites mentioned. The description only focuses on what the tool does, not on usage 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 should cover behavioral traits, but it only mentions the return structure and parameter type, omitting authentication, error handling, or 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 short and front-loaded, but lacking structure and detail makes it only adequate.

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 presence of an output schema, the description should still clarify the 'five columns' and sheet content; it does not, leaving gaps 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 0%; the description only restates that sheet_id is a string without explaining its role or format, adding minimal 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 it reads feedback sheet details with structure {ok, sheet}, distinguishing it from sibling tools like list_feedback_sheets and upsert_feedback_sheet.

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

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

No guidance is provided on when to use this tool versus alternatives, nor are any conditions or exclusions mentioned.

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 fully discloses behavior: text extraction method, placeholder format for examples, aggregation of fragments for lesson nodes, empty state handling, and owner view priority. No contradictions.

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 well-structured with bullet points, warnings highlighted, and key information front-loaded. Every sentence serves a purpose; no fluff.

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

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

Given the complexity, the description is complete: covers purpose, parameter usage, return fields, edge cases (empty content), and follow-up actions. Implicit output schema in text is 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?

Despite 0% schema description coverage, the tool description provides extensive semantics for all three parameters: subject_id source and aggregation, book_id default, owner fallback logic, and expected values. Adds significant value beyond the bare 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 retrieves lecture content for a knowledge point/lesson, explicitly positioning it as the raw material for generating questions. It distinguishes from sibling tools like save_lecture_frag by focusing on reading, and references get_question for follow-up.

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 guidance on how to obtain subject_id via other tools, explains the behavior for different parameter values (e.g., empty book_id, owner fallback), and instructs the agent to degrade to KG + question bank when has_content is false. Lacks explicit contrast with all siblings but covers essential usage.

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, description discloses it's a read operation returning {ok, plan, lessons}. It details return fields and their usage, but lacks explicit read-only assertion.

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?

Description is structured with bullet points and emojis for clarity, front-loaded with purpose. Slightly lengthy but well-organized.

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

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

Output schema exists and is fully described inline. Every field is explained with usage hints and cross-references to other tools, making it self-contained.

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 0% description coverage, but description details plan_id as '课程计划 id（字符串雪花号）' and explains how to obtain it from list_schedule, adding meaning beyond 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?

Description states verb '读' (read), resource '课程计划' (course plan), and result '全部课次明细' (all lesson details). It distinguishes from sibling tools like list_schedule by explicitly pointing out that it fills the gap of reading full lesson details.

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?

Description advises using before lesson prep: '备课前读「这节课的编排蓝本」'. It explains it fills a gap in the current chain but does not explicitly state when not to use.

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?

Without annotations, the description fully covers behavioral traits: round-trip semantics, rotating items returned without question text, review status structure, and that blocks are assembled by the backend. This is comprehensive.

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 concise but information-dense, using bullet points and icons to convey key points. It is front-loaded with purpose and every sentence adds 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?

Given the presence of an output schema, the description provides enough context on the return structure and round-trip semantics. It covers the main components and how to use the tool in conjunction with upsert_punch_day.

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

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

Schema coverage is 0%, so the description must explain parameters. It does: book_id as string, day as integer (1-indexed). However, it doesn't elaborate on constraints like format or range, but it's sufficient for basic usage.

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 reads back the full content for a given day, listing the fields (ok, goals, modules, review). It distinguishes from siblings like list_punch_days and upsert_punch_day by specifying its role in the round-trip workflow.

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 explains when to use this tool: before modifying a day's content (get full data, then modify and upsert). It also notes that for rendering previews, a different endpoint should be used.

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. It discloses multiple behavioral traits: auto-filtering of soft-deleted questions, ordering by input order, structure of options (in block_json), and maximum batch size. No contradictions with annotations (none exist).

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

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

The description is concise yet comprehensive, structured with bullet points for parameters and return fields. Every sentence adds value: purpose, API endpoint, parameter details, return format, and special notes about options. No redundant information.

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 simplicity (one parameter, output schema described), the description covers all necessary aspects: input constraints, output fields, ordering, filtering, and behavior for question types. It is complete for an AI agent to invoke 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 input schema has zero description coverage for the 'ids' parameter. The description adds significant meaning: the type (strings, snowflake numbers), constraints (single call ≤100), and behavior (order preserved). This fully compensates for the schema 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 the action ('按id批量拉题目详情') which is retrieving question details by IDs. It distinguishes from sibling tools like search_questions (for searching) and delete_questions (for deletion) by specifying batch retrieval by ID list.

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

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

The description includes a warning ('装段前人工核对') indicating when to exercise caution, and mentions constraints like max 100 IDs. However, it does not explicitly contrast with alternatives or state when not to use the 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?

No annotations exist, so description carries full burden. Discloses return format {ok, role, manual} and error case {ok:False, hint}. Since it's a read-only retrieval, no major behavioral traits missing.

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?

Description is detailed but well-structured with bullet points and sections. Every sentence adds value; could be slightly trimmed but overall efficient for the information density.

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 one optional parameter and existence of output schema, description fully covers tool behavior, input meaning, output format, and error handling. No 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?

Input schema has one param 'role' with default but no description. Description fully compensates by explaining each possible value ('data','ingest','lecture','prep','variant','all') and their corresponding manual content, providing complete semantic 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?

Clearly states it retrieves the full role manual, distinguishes from sibling tools like get_feedback_sheet, and specifies each role's content. Mentions alternative MCP resource for specificity.

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, e.g., first-time agents should call with corresponding role; suggests role='all' for fresh agents. No explicit when-not, but context suffices. Also references a resource alternative.

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 reveals the return structure and mentions the endpoint ':9090', but does not disclose potential side effects, authorization requirements, or error handling behavior (e.g., what happens if target_id is invalid). The addition of 'error_signals' adds useful context, but more behavioral clarity is needed for a complete picture.

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 concise, with only two sentences and a parameter list. It front-loads the core purpose and return format. Every piece of information is relevant, and there is no redundancy. The structure is efficient and easy 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?

Given the tool has 2 parameters and an output schema (not shown but referenced by return format description), the description covers the essential: purpose, parameters, and return structure. It does not provide error handling or edge cases, but it is sufficient for typical use. The context of preparing lessons is included, which adds situational 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?

The description provides explicit parameter descriptions beyond the schema: 'target_id: 对象 id（字符串）' and 'target_type: 'student'（默认）| 'class''. Since schema coverage is 0%, this compensation is valuable. The description adds default value and allowed values, making it easy for an agent to understand usage.

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 fetches object details and portrait including error signals ('取对象详情 + 肖像（含 error_signals 易错库）'), and specifies the return format '{ok, target, profile}'. This distinguishes it from other tools like get_feedback_sheet or search_questions, as it is specifically for student profiles with error signal data.

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 mentions when to use this tool: before lesson preparation ('备课前读画像') and to view pending error signals after recycling ('看回收后新增的 pending 易错信号都走它'). While it does not list exclusions or alternatives, the context is clear and practical for an AI agent deciding on 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?

Description discloses key behaviors: trust_env=False, timeout 5s, specific endpoints per service, and that 401 for ruoyi is considered up (auth needed). It also states that any exception results in 'down' and no exceptions are thrown. With no annotations, this level of detail is commendable.

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?

Description is concise, well-structured with bullet points for each service. Every sentence adds value. No redundant or missing information.

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 zero-parameter health check with an output schema, the description covers return structure, behavior, edge cases, and nuances (e.g., 401 handling). It is complete and actionable.

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 zero parameters and schema description coverage is 100%. Description does not need to add parameter info. Baseline score of 4 applies as no parameters exist.

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

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

Description clearly states it checks three dependencies (ruoyi BE, toolkit, MySQL) and returns status objects. It uses specific verbs ('探活') and resources, and distinguishes from sibling tools which are all action-oriented (e.g., login, search, delete).

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

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

No explicit when-use or when-not-use guidance. However, the tool's purpose as a health check implies it should be used for verifying service status. No alternatives are mentioned, but no sibling tool serves this purpose.

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 fully carries the burden. It details every step: image upload to OSS, blockJson formatting, question recording, knowledge mapping, labeling, paper creation, unknown field rejection, duplicate detection, and serial execution for new_models. The return values and batch_id usage are fully explained.

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 fairly concise given the complexity, front-loading the main purpose. It uses bullet points and structured sections. However, it could be slightly more succinct without losing information.

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, the absence of annotations, and presence of an output schema, the description covers all behavioral, return, and usage aspects. It references AC3, AC4, and PRD-O-005, and connects to sibling tools like 'search_questions' and 'my_recent_uploads'. No gaps remain.

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 the input schema itself provides rich descriptions for each parameter, the tool description adds value by explaining the workflow context (e.g., image handling order, serial model proposal) and high-level relationships. The 0% schema coverage in context is inconsistent with the provided schema, but the description compensates adequately.

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 it is a unified ingestion endpoint ('统一入库口') that handles questions, images, knowledge points, labeling, and optional paper creation in one call. It distinguishes from sibling tools like 'ingest_question' (singular) and 'compose_paper' by emphasizing batch and combined functionality.

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 on when to use (for unified ingestion from seven sources) and references 'get_role_manual' for contract details. It mentions duplicate handling and dual pipeline marking, but does not explicitly exclude alternative tools or state when not to use.

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 behavior: it returns a structured response with fields like ok, question_id, created, import_source, batch_id; explains the dual-pipeline semantics for import_source; and specifies error behavior ('底座报错 → {ok:false, reason}'). This covers safety and side effects adequately.

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 well-structured with bullet points and clear headings. It front-loads the return type and uses a concise table-like format for parameters. Every sentence earns its place without 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?

Given the complexity (18 parameters, 4 required, no annotations, output schema present), the description is complete. It explains the output return structure, all parameters thoroughly, and interactions with other tools (e.g., upload_image, format_question). No gaps are left.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. It explains each parameter's meaning, constraints, defaults, and relationships (e.g., free_tags linked to biz_free_tag, knowledge_ids linked to list_kg_tree). This adds significant value beyond the bare 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 action: '录一道题入库（事务多表）' (ingest a question into database with multi-table transaction) and associates it with the current teacher. It distinguishes from siblings like search_questions and delete_questions by specifying it is a creation operation.

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

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

The description does not explicitly state when to use this tool versus alternatives. While it is implied for adding a single question, there is no guidance on prerequisites or when not to use it. Sibling tools like 'ingest_items' potentially serve a similar batch purpose, but no comparison is made.

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 describes that the tool updates the question's DNA labeling, lists parameters with constraints, and specifies the return format including error handling. It does not explicitly mention side effects or permissions, but overall provides good behavioral detail.

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 lengthy but well-structured with clear sections: purpose, prerequisite, parameter list, and return values. It front-loads the main purpose and uses a bullet-like format for parameters. Some information could be consolidated, but it remains clear and 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?

Given the complexity (17 parameters, 2 required) and no annotations, the description covers all necessary aspects: prerequisites, detailed parameter meanings, return values, and error handling. It is fully sufficient for an agent to select and 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 description coverage is 0%, so the description must compensate. It does so thoroughly, explaining each parameter's role, constraints (e.g., difficult rubric, controlled vocabularies for hard_points and scenario), and how to fill them. This 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 clearly states the tool's purpose: to write DNA labeling (difficulty, knowledge anchor, solution skeleton, variant base material) for an already ingested question. It uses specific verbs and resources, and distinguishes itself from siblings like ingest_question by explicitly requiring prior ingestion.

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 the prerequisite (question must be ingested via ingest_question) and suggests that Claude should read the question and KG context before calling the tool. It does not explicitly name alternatives or when not to use, but the context provides sufficient 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 provided, so the description carries full burden. It discloses return structure and statistical fields, and implies read-only behavior with owner filtering.

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?

Extremely concise, with no wasted text. Front-loaded purpose, immediate filtering info, and explicit return format.

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?

Describes return shape and purpose of statistical fields, but omits pagination, ordering, and error handling, which are minor given the tool's 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 coverage is 0%, and description mentions optional filtering by status, book_type, subject_id, but lacks details on valid values or formats.

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 it lists books with automatic owner filtering and optional filtering by type, subject, and status, distinguishing it from sibling tools like create_book and get_book_structure.

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

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

Provides clear context for use (listing books with filters) but does not explicitly state when not to use or mention 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?

No annotations are present, so the description carries full burden. It is a read-only operation returning a list, but it does not explicitly state it has no side effects or requires no authentication. The return format is clear, but behavioral traits beyond the data are not 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 front-loaded with purpose, then provides a detailed but somewhat long list of grade-specific categories. Every sentence contributes information, but it could be more concise by grouping categories without enumerating every single entry.

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

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

With no parameters and an output schema existing, the description fully covers the return format and enumerates all 46 categories, leaving no ambiguity about what the tool provides.

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?

There are zero parameters, so baseline is 4. The description adds value by detailing the structure of each item (code, name, grade, term) and the overall return schema, which is not present in the input schema since there are no 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 explicitly states the tool returns a 'full table of calculation types' covering 46 categories for grades 1-6, with specific grade and term breakdowns. The verb 'list' and detailed contents clearly distinguish it from sibling tools like generate_calc_paper.

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 does not provide any guidance on when to use this tool versus alternatives. It only describes what data it returns, with no context on prerequisites, scenarios, 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?

Without annotations, the description bears full burden. It reveals the output format, ordering (newest first), owner isolation, and three filtering parameters. It does not explicitly state it is read-only, but the context implies it. Overall, good 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 concise yet informative, with a clear structure: purpose, output fields, usage guidelines, parameter list. The use of emoji and breaks aids readability, though it could be slightly shorter without losing clarity.

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 three optional parameters, no required ones, and an output schema (which is not detailed but the description lists key fields), the description covers use cases, output structure, and filtering options adequately. It leaves little ambiguity for an AI 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 has zero description coverage, but the description adds meaning for all three parameters: target_id (optional), keyword (fuzzy title match), batch_key (filter to specific batch PRD-010). This compensates well for the schema's lack of documentation.

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

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

The description clearly states the tool lists feedback sheets under the current teacher with owner isolation, returning {ok, rows, total}. It distinguishes itself from siblings like get_feedback_sheet (likely single fetch) and upsert_feedback_sheet (create/update) by focusing on listing and 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 explicit usage guidance with red markers: use this to find a target ID before editing to avoid duplicates, and check the latest batch and lesson sequence before continuing to the next lesson to set the correct lesson_seq. This clarity on when and why to use the tool is exemplary.

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 fully bears the burden and delivers: it explains the return format, nesting structure, and empty tree handling. This enables the agent to predict behavior accurately.

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 concise, front-loading the main action. It includes usage context and return format in three sentences, which 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?

Given zero parameters and an output schema that is partially described, the description is complete. It covers the return type, structure, and edge case (empty tree), and explains how the output is used.

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

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

The tool has zero parameters, so the description does not need parameter details. Baseline is 4 as per guidelines, and the description adds no unnecessary param info.

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 queries the knowledge point tree for composing papers. It specifies the return structure (top-level nodes with children) and its role in feeding IDs to compose_paper, distinguishing it from sibling tools.

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

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

The description implies usage before compose_paper to obtain subject IDs, providing clear context. However, it lacks explicit when-not-to-use or alternative tools, which is acceptable given the specific role.

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 provided, but description fully discloses the GET request, return structure, empty state behavior, and evolution of backend structure. Lacks details on authentication or side effects, but as a read list, it's sufficient.

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?

Description includes implementation details (port, endpoint) that are not essential for an agent, but is still relatively short. Could be more streamlined.

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

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

Covers purpose, parameter, return structure with example fields, and edge case (empty catalog). Missing error handling details, but output schema likely fills that gap.

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 0% coverage, but description explains the single parameter book_id with default behavior (empty = server default), adding 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 clearly states the tool lists the lecture catalog, specifying which class hours/knowledge points have fragments, and distinguishes from siblings like get_lecture_content by focusing on the index/catalog.

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

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

Usage is implied (to find lectures with fragments for question generation), but no explicit when-to-use or when-not-to-use as compared to other lecture 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?

Discloses important behavioral traits: the destructive effect on review status when reimporting a passed day, and explains the review substructure. No annotations exist, so the description carries full burden and does so effectively.

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?

Concise and well-structured: first line states purpose and return format, then explains review substructure, followed by a critical usage warning, and ends with parameter note. No unnecessary words; every sentence adds 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?

Complete for a simple list tool: covers purpose, return format, review substructure, behavioral warning, and parameter. Given that an output schema exists, the description adequately explains what the tool does without over-specifying.

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?

Only one parameter (book_id) with no schema description (0% coverage). The description mentions the parameter as a string but adds no additional meaning beyond the schema. With low coverage, the description should compensate, but the parameter is simple and the explanation minimal.

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 the tool lists all punch days of a book along with review status, specifying the return structure. It distinguishes from sibling tools like get_punch_day (singular) and upsert_punch_day.

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: use before reimporting a day to check existence and review status. Warns that reimporting a passed day resets review. No explicit alternatives are given, but the 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?

The description mentions it returns {ok, sessions} and lists output fields, but does not disclose behavioral traits such as permissions required, side effects, rate limits, or the significance of the ':9090' port. Since no annotations are provided, the description should reveal more about safe usage.

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 relatively concise and front-loaded with the purpose, then the return format and parameters. However, the mention of ':9090' seems like an internal detail that may not be necessary for the AI agent and adds slight noise.

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 that the output schema exists (mentioned as 'has output schema: true'), the description covers the return structure. Parameters are fully explained. Missing details like pagination, error handling, or default sorting are minor for a simple listing 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 description thoroughly explains all three parameters: start and end date formats (YYYY-MM-DD, inclusive) and target_id (filter by object, omit for all of user's own). This adds essential meaning beyond the bare schema, which has no property 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 clearly states the tool's purpose: listing calendar sessions for a given time window, and specifies the returned fields (object name/color, time, lesson title, type, preparation status). It distinguishes from siblings like 'schedule_sessions' and 'update_session' by being a read-only listing tool.

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

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

No explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. Usage is implied by the parameter explanations and the fact that it lists sessions, but no when-to-use or when-not-to-use instructions are provided.

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

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

No annotations provided, so description carries burden. Clearly indicates it's a query operation ('查') returning {ok, items} with real-time aggregation. Could be more explicit about being read-only and safe, but sufficient given no destructive traits.

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?

Compact and front-loaded: first line states purpose and features, then usage guidance, then return format, then parameter details. Every sentence adds value with no 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?

Covers purpose, usage, parameters, and return format. Mentions aggregation fields but doesn't detail them. Output schema exists but not shown; description is complete enough for agent to use 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 0% but description fully explains all three parameters: target_type ('student'|'class', omit for both), keyword (fuzzy name filter), include_archived (True includes archived, default False). Adds meaning beyond 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 it lists teaching target cards with real-time aggregation, using specific verbs ('查' - query) and resources. It distinguishes itself from sibling CRUD tools like create/update/archive targets.

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 instructs to use for duplicate checking before creating targets and for selecting scheduling targets ('建对象前查重、选排课对象都走它'), providing clear when-to-use and contextual 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 provided, so description carries full burden. It discloses token stays server-side, permission audit, and .env fallback. Sufficiently transparent for a login tool.

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

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

Description is concise, front-loaded with the action, and each sentence adds necessary detail without waste.

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

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

Despite having an output schema (not shown), description explicitly states return shape {ok, teacher_id, username} and token behavior, making it complete for a simple login 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 coverage is 0%, but description explains username/password as teacher accounts and that blank values default to .env variables. Adds meaning 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?

Description clearly states that the tool logs in to the platform with a real teacher account and injects a session token. It doesn't explicitly differentiate from the sibling 'login_as', but the action is well-defined.

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

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

No guidance on when to use this tool versus alternatives like 'login_as'. The description implies it's for initial login but lacks explicit usage 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 provided, the description takes on the full burden of behavioral disclosure. It explains the authentication mechanism (BOT_SECRET, not requiring caller password), the side effect of replacing the session identity, and the automatic 401 retry behavior. The return structure also details success/error cases. It does not mention rate limits or idempotency, but overall it is sufficiently 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 well-structured with labeled sections (用途, 鉴权, 401自动重签, 参数, 返回). Every sentence contributes necessary context—purpose, authentication, retry behavior, parameters, and return values—without redundancy. It is front-loaded with the core purpose, making it easy for an AI agent to quickly grasp the tool's role.

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 a single parameter, an output schema effectively documented in the description, and behavioral details, the description is comprehensive. It covers all essential aspects: what the tool does, how authentication works, side effects, and what results to expect in success and failure cases. No significant gaps remain.

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

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

The input schema has 0% description coverage, but the description adds a clear definition for the sole parameter 'openid': it provides the type ('飞书 open_id') and an example ('ou_xxx'). This meaningfully supplements the schema, which only declares the parameter as a string without further explanation.

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 is for identity switching in a Feishu bot using a service secret to exchange open_id for a teacher's token. It explicitly says it replaces the current session identity, and the '用途' section explains the per-message identity switching scenario. This distinguishes it from siblings like 'login' (presumably for initial authentication).

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 '用途' section specifies that this tool is used on a per-message basis to make write operations belong to respective teachers. It also mentions that after switching, subsequent tools automatically handle token re‑issuance on 401. However, it does not explicitly state when NOT to use it or provide a direct comparison with 'login', leaving some ambiguity for the AI agent.

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 provided, so the description carries full burden. It explains the creation workflow, timing (~60s), rendering bypass, error states (mother_card=None), and next steps. It lacks explicit mention of destructive behavior but implies creation only. Could clarify authorization needs.

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

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

The description is well-structured with bullet points and clear sections. It is somewhat lengthy but each sentence adds value given the tool's complexity. Could be slightly more concise, but not excessively verbose.

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, the output schema exists, and the description thoroughly covers return fields (status, mother_card, kg_candidates, etc.) and their meanings. It also explains the rendering bypass and thread_id persistence. Complete for agent use.

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

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

Schema coverage is 0%, but the description compensates fully. It explains each parameter's purpose, format, default, and behavior (e.g., priority, auto-generation of thread_id, hint default). This is essential for correct invocation.

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: generating variant questions (mother card) from an image, text, or question ID. It uses specific verbs like '出母题卡' and distinguishes from siblings like generate_variants and confirm_variant_chapter.

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 each input method with priority order, how to proceed based on status (need_confirm vs ready), and the role of thread_id for continuation. It also references sibling tools for follow-up actions.

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 fully discloses that the tool is read-only, defines the parameter behavior (hours, default 24, <1 treated as 1), explains the return structure grouping by import source, and notes the dual pipeline semantics. Missing details on pagination or limits for results.

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 well-structured with sections for purpose, usage, parameter, return format, and a note. It is front-loaded with the main verb and resource. While slightly lengthy, every sentence adds value and uses formatting (emojis, bold) for clarity.

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 parameter, return structure with three object types, grouping, and a view URL. It explains the import_source prefixes. However, it does not mention behavior when no results exist or if hours exceeds some maximum.

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

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

Schema coverage is 0% (no parameter descriptions in schema), but the description explains the 'hours' parameter: it's a time window with default 24 hours and behavior for values less than 1. This adds meaning beyond the schema's type and default.

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 retrieves recent uploads (questions, papers, lecture fragments) for the logged-in teacher. It uses specific verbs like 'retrieve' and 'group by batch', and distinguishes from sibling tools like search_questions by noting it's DB read-only and doesn't rely on stem keywords.

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 use case: after MCP recording the teacher wants to quickly check what was just uploaded. It specifies the hours parameter and default behavior. However, it does not explicitly exclude use cases or compare to similar tools like list_lecture_docs.

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 effectively discloses behavioral traits: it writes to 'item.override_json', preserves the question_id trace ('血缘不断'), and notes that mathematical symbols like '<>' are not stripped by XSS. It also specifies the return format as '{ok}', giving full transparency for a safe mutation operation.

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

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

The description is concise, consisting of four short sentences that are front-loaded with the main purpose. Each sentence adds unique value, covering scope, behavior, revert mechanism, and safety features, with no wasted words.

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

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

Given the tool's complexity (two parameters, nested objects, and an output schema), the description covers the core functionality well. It explains the effect, reversion, and safety, but could be enhanced by mentioning error cases or required permissions. Still, it is adequate 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?

The schema has 50% coverage (only 'override' has a description). The tool description adds value by explaining the effect of 'stem' and 'options' being written to 'override_json' and clarifies that passing an empty override ('{}') resets to original. However, 'item_id' remains undocumented, though its purpose is inferable from 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 clearly states the tool modifies a question's stem/options within a book without affecting the original item in the question bank ('只影响本书，题库原子题**不动**'). The verb ('改') and resource ('一道题的题面') are specific, and the scope is well-defined, distinguishing it from global edits.

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 when to use this tool (for per-book overrides) and how to revert ('还原原题 = 传空 override（{}）即清'). However, it does not explicitly mention when not to use it or suggest alternatives, though the context implies differentiation from sibling tools like 'edit_variant'.

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 details the rule-based splitting process, state machine for sub-questions, answer backfilling, and figure placeholder handling. It also warns about potential num misalignment. However, it does not explicitly state if the tool is read-only or modifies data.

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 somewhat lengthy but each sentence adds value. It is well-structured with purpose, rules, usage notes, parameter info, and return format. The front-loading of the main function is good, though some sentences could be merged for brevity.

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 existence of an output schema, the description still explains the return fields (ok, count, questions with subfields) comprehensively. It provides all necessary context for an agent to use the tool and process results 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 0%, so description must compensate. It explains that 'text' is the paper text, mutually exclusive with 'text_path', and that 'text' takes priority. It adds useful semantic info beyond the schema, though 'text_path' could be more clearly described.

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 converts standardized exam paper text to a JSON list of questions using deterministic rules. It mentions suitability for convert_doc output, providing context, but does not explicitly differentiate from all sibling tools beyond that.

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 (suitable for convert_doc output or pasted text), explains how to use the output (verify count, construct IngestItem[]), and warns against using 'num' for sorting. It also clarifies parameter selection (text preferred over text_path).

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 partially covers behavior: it indicates the tool is a write operation (storing), mentions ownership by logged-in teacher, and outlines return values. However, it does not disclose mutability, idempotency, or full authorization requirements.

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 concise, with a clear structure: action, prerequisite, parameters, return value. Each sentence contributes meaning, though it could be slightly more streamlined.

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 purpose, parameters (mostly), and output format. However, the required thread_id parameter is not defined, and the 'manual' reference is vague. For a tool with two parameters, this is adequate but not fully complete.

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

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

Given 0% schema description coverage, the description compensates well by explaining item_ids (optional list, default stores all) and the return structure, but does not explain the required thread_id parameter beyond its name.

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: store variants into database to get real question IDs. It distinguishes itself from siblings by mentioning the prerequisite verify_variant, though not explicitly comparing with other tools.

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

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

The description specifies a prerequisite (verify each variant before storing) and explains default behavior for the item_ids parameter, but lacks explicit guidance on when not to use this tool or alternatives.

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