teacher-mcp
Server Quality Checklist
Latest release: v2.0.0
- Disambiguation4/5
Most tools have distinct purposes with detailed descriptions, but the sheer number (71) and subtle overlaps (e.g., login vs login_as, compose_paper vs create_paper) may cause occasional confusion. Overall clear, but not completely unambiguous.
Naming Consistency5/5All tools follow a consistent verb_noun pattern (e.g., list_kg_tree, search_questions, upload_image). Naming conventions are uniform across the entire set, making it predictable for both agents and developers.
Tool Count1/5With 71 tools, the surface is highly excessive. While the domain is broad, this many tools overwhelm the agent and violate the ideal scope of 3-15. Scores of 50+ are extreme mismatches per the rubric.
Completeness3/5The tool set covers most major workflows (CRUD for questions, books, plans, feedback, variants), but lacks a dedicated update_question tool, which is a notable gap. Otherwise, lifecycle coverage is reasonably thorough.
Average 4.4/5 across 71 of 71 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 64 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
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.
Conciseness4/5Is 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.
Completeness3/5Given 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.
Parameters1/5Does 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.
Purpose4/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness3/5Is 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.
Completeness2/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior3/5
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.
Conciseness4/5Is 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.
Completeness3/5Given 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.
Parameters4/5Does 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.
Purpose4/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters3/5Does 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.
Purpose4/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose4/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose4/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full responsibility. It discloses the upload action, deduplication behavior, and return fields (ok, asset_id, oss_url, dedup). This provides good transparency, though it could mention permissions or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently cover purpose, parameters, and return format. It is front-loaded and to the point, but could benefit from slightly more structured breakdown.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and presence of an output schema, the description covers purpose, parameters, and return values adequately. It explains the integration points (blockJson, ingest_question.images), but lacks details on error handling or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 local_path as local absolute path and asset_kind as asset type with example 'figure'. While it adds meaning beyond the schema, it could provide more detail on the asset_kind options or path format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it uploads a local image to OSS with deduplication, returning an ossUrl usable in blockJson or ingest_question.images. It distinguishes from siblings by specifying the exact use case and output integration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used for uploading local images for use in blocks or ingest_question, but does not explicitly state when not to use it or provide alternatives. The context is implied but not fully directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness3/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses relevant behaviors: return object with ok/created/conflicts, conflict handling logic with force, auto_bind functionality, and the endpoint. It does not mention authentication or permissions, but covers main behavioral aspects well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief purpose statement followed by key behavioral notes and a bulleted parameter list. However, it includes some unnecessary details (e.g., ':9090' endpoint, '🔴 冲突处理（契约 D6）') that may distract. Overall, it is fairly efficient for the complexity involved.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, no annotations, no schema descriptions), the description covers inputs, behavioral nuances, and output format thoroughly. It lacks explicit prerequisites (e.g., target must exist) but is otherwise complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must fully explain all parameters. It does so exhaustively: target_type with enum values, target_id, items with nested fields (date, start, end, plan_lesson_id, session_type, external_title, note), plan_id, auto_bind, and force. Each parameter is clearly defined, adding significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs batch scheduling for a target (student or class), with a specific verb ('批量排课') and resource. It distinguishes from siblings like update_session, but does not explicitly differentiate from other scheduling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context: it explains when to use auto_bind and force for conflict handling, and mentions the return format. However, it does not explicitly compare to alternative tools (e.g., when to use this vs. update_session), making usage guidance implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness3/5Given 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.
Parameters1/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness3/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it does nothing except return a retirement guidance message. It explains the deprecation reason and confirms no operations are performed, which is complete transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear deprecation header, explanation, and replacement steps. It is somewhat lengthy but all information earns its place; however, it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's deprecated status, the description covers the essential behavioral change and replacement. However, it omits details about output schema (which exists) and actual response format, leaving some gap in completeness for a tool with a defined output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the two parameters (pack_id, mark_ready) or state that they are ignored. Since schema description coverage is 0%, the description should compensate but fails to provide any parameter semantics, leaving the agent confused about their relevance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states that the tool is deprecated and only returns deprecation guidance, no longer performing any operation. This is a specific verb-resource pair that clearly distinguishes it from active sibling tools like compose_paper and 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.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-not-to-use instructions and directs users to the replacement workflow (compose_paper/create_paper + bind_paper_slot) and to get_role_manual for further guidance. This explicitly differentiates from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior3/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It discloses deterministic generation, OSS upload behavior with login requirement, and return format. However, it does not cover error handling or rate limits, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, structure spec, example, parameters, return, usage). Every sentence adds value, and the most critical information is front-loaded. No unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool, the description covers input structure (puzzles with rows, op, cells), parameters, output fields, and usage context (blockJson, ingest). It also includes edge cases like 'HR' for horizontal lines and answer version handling. No output schema is provided, but the description compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for top-level parameters, but the description thoroughly explains each parameter, including upload's OSS dependency and out_name's custom filename, and provides a complete example for puzzles. 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates PNG figures for 'shuzimi' puzzles with specific structural rules. It uses a specific verb ('render') and resource ('shuzimi figure'), but does not explicitly differentiate from sibling tools like compose_variant_figure or render_prep_pack.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning how to use the output (e.g., oss_url for blockJson) and that the answer version requires replacing '?' and calling again. However, it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose4/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It details side effects (marks session as done), computational behavior (parent_msg generated on-demand, not stored), filtering (internal words filtered out), how portrait_delta is computed and appended, and idempotency (repeated submission overwrites with previous in prev_json).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a summary first line, then bullet points for key behaviors, and a parameter list. It uses emojis for emphasis. Slightly verbose in places but generally efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, 2 required, no schema descriptions, no annotations, but output schema exists), the description covers purpose, parameters, behavioral details, return structure, and side effects. It is appropriately complete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% coverage (no descriptions), but the description compensates thoroughly. It explains session_id as 场次 id, item_results as an array with nested structure including fields like question_id, seg, seq, result (with allowed values: 对|错|卡), and cause (枚举: 计算|概念辨析|策略|其他). teacher_note and parent_msg_override are also explained with context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '课后回收' (after-class review) to record per-question correctness, generate parent feedback, and update student portrait. It specifies the return structure and distinguishes itself from siblings like 'submit_punch_review' by focusing on session review rather than punch cards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. It mentions that submission marks the session as done, but provides no guidance on when to use submit_review vs. other feedback-related tools like upsert_feedback_sheet or get_feedback_sheet.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure. It explicitly states the tool is '确定性只读' (deterministic read-only). It explains the leaf detection nuance (use is_leaf not level) and return format. It does not mention rate limits or auth requirements, but for a read-only tool, the transparency is good.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but well-structured with sections and bullet points. It is not overly verbose; each part adds value. However, it could be slightly more concise, e.g., by reducing the redundancy of the leaf depth explanation. Overall, it balances detail with readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, one required) and no formal output schema, the description covers all necessary aspects: purpose, parameter usage, behavioral notes, return format, and edge cases (no matches return count=0 without error). It also provides a workflow context for downstream tools (ingest_items). This is comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds substantial meaning to all 6 parameters. It provides example values for subject_root (e.g., '100' for Math Grade 7), explains the effect of parent_id overriding subject_root, and clarifies the use of leaves_only. This goes well beyond the schema's basic types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'KG 锚定查表（确定性只读，数学+科学一套通吃）' indicating it is a read-only lookup in a knowledge graph for math and science. It specifies the actions: query by name, section number, or parent node under a textbook root. While it does not explicitly differentiate from sibling 'list_kg_tree', the description implies this tool is for targeted anchored lookup, not tree exploration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear workflow: first use query fuzzy to find candidates, then pick a leaf node (is_leaf=true) as kp_id for ingest_items. It also covers exact match by section_num for exercise papers. However, it lacks explicit 'when not to use' or comparison to alternatives like list_kg_tree, slightly reducing the score from 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes the scoring rules for different question types, the persistence via /update, and the return format including error handling. It does not mention any destructive actions or side effects beyond updating the paper.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but well-structured: first explaining the core action, then scoring rules, then parameter list with defaults, and finally return format. Each sentence adds value, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary aspects: purpose, input parameters (with defaults), behavior (scoring rules and persistence), and output format. Since an output schema exists, the description's inclusion of return details is helpful but not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates fully by explaining each parameter: paper_id identifies the paper, total_score is total score (default 120), suggest_time is suggested minutes (default 120). It also clarifies default values and the role of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to calculate per-question scores based on grade-standard scores and set suggested time, then persist via /update. It specifies the verb '给试卷按年级标准分(通值)算每题分值 + 设建议时长' and distinguishes from sibling tools like compose_paper or create_paper by focusing on updating an existing paper's scoring and time.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: after a paper is created, to set scoring and suggested time. It does not explicitly state when not to use it or mention alternatives, but the context from sibling names (e.g., create_paper) makes it clear this is an update operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 what the tool checks (residue prefixes), that ingest_items already prevents them, and describes the return value and its meaning. It does not mention side effects, but given the tool is likely read-only, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with an emoji and bold text. Every sentence is relevant. The structure could be more organized, but it effectively communicates key information without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple purpose (verification), the description covers all necessary aspects: purpose, parameters, usage, and return value. The tool has an output schema, and the description explains its shape adequately. It is complete for this level of complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description fully explains the two parameters: paper_id for checking an entire paper, question_ids for specific questions, and that they are mutually exclusive. This adds significant value beyond the schema, which only provides types and defaults. Schema description coverage is 0%, so the description compensates completely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to verify that ingested test papers have no residue prefixes. It uses a specific verb ('verify') and resource ('ingest'), and distinguishes itself from sibling tools like ingest_question and ingest_items by being a post-ingest verification step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: '每次灌完卷/批必须跑一次' (must run every time after ingesting a paper/batch) and that residue_count must be 0. It does not mention alternatives or when not to use, but the 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden. It discloses stateless recomputation, approximate timing (~17s), and defines each verdict type (pass/fail/degrade). Adds useful behavioral context without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with three clear sections: purpose, parameters, return. However, the parameter explanation could be slightly more structured. Overall efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (verification with specific output), the description covers purpose, parameters, return format, and verdict semantics. The presence of an output schema reduces the need to describe return values, but the description still adds value. Complete for a verification tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (description not in schema), but the description explains item_id as the variant ID returned by generate_variants, equals seq, and is a string. This adds meaning beyond the schema's bare type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it independently verifies a variant via stateless Sympy recomputation and provides a verdict. Names specific verb 'verify' and resource 'variant', distinguishing it from siblings like 'generate_variants' and 'persist_variants'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states it must be used before persist ('persist 前须逐题过'), providing usage context. Does not explicitly list alternatives, but the strong precondition effectively guides when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: side effects (auto book marking on pass, issue tracking, status resets on reopen), action constraints (only three values allowed), and interaction with other tools (upsert_punch_day for re-upload). It does not mention authorization or rate limits but covers critical behaviour well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points for actions and parameters, front-loaded with the main purpose. Every sentence adds value, and the length is appropriate given the complexity. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity, lack of schema descriptions, and no annotations, the description is remarkably complete. It covers purpose, all parameters with semantics, side effects, workflow context (e.g., major changes require other tools), and even hints at the return value ({ok, review}). The presence of an output schema does not detract from the description's completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description compensates fully. It explains each parameter: book_id (string), day (integer starting at 1), action (enum with three values), and issues (array required for issue action, with subfields module, seq, kind, note). It also clarifies the meaning and constraints of each action value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: submitting human eye review conclusions for a specific day, with three distinct actions (pass, issue, reopen) and their consequences. It distinguishes the tool from siblings by focusing on the punch day review closure, and references related tools (upsert_punch_day) for different workflow steps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context for each action (e.g., what happens on pass, issue, reopen) and notes that major changes should not be handled with this tool but via other processes. However, it does not explicitly compare to sibling tools like submit_review, leaving some ambiguity about when to use this versus related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It discloses upsert behavior (PUT vs create), target_id validity requirement, title visibility to parents, structured rows with required fields, and mastery phrasing constraints. Lacks info on rate limits or auth but these are less critical for this tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is fairly long but well-structured: starts with a concise purpose, then explains batch context, followed by bulleted parameter list. Every sentence adds value; the length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, batch logic, and output schema (defined as {ok, sheet_id}), the description is quite thorough. Covers workflow, constraints, and parameter details. Minor gaps: rows structure could specify that kp_id is optional, and no mention of error handling or limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It explains all 7 parameters: target_id (mapped from list_teach_targets), title (parent-visible), lesson_date (format), rows (required keys), sheet_id (update), batch_key and lesson_seq (continuation logic). Adds significant meaning beyond bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states '建/改课后反馈单' (create/update after-class feedback sheet) and specifies the output '{ok, sheet_id}'. Distinguishes from siblings like 'list_feedback_sheets' and 'export_feedback_png' by focusing on upsert operation with batch logic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides detailed usage guidelines: explains batch concept (PRD-010 workflow), how to determine next lesson_seq using list_feedback_sheets, when to start a new batch, and warns against fabricating target_id. Although no explicit 'when not to use', the rich guidance compensates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses destructive behavior: deletes fragments and may delete attached mindmap. Includes constraints, return format {ok, removed}, and workflow context (override step). 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is dense with useful info but well-structured: purpose sentence, warning block, parameter list. Slightly verbose but front-loaded and organized. Could be trimmed but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: purpose, destructive behavior, constraints, parameter defaults, return format, prerequisite (login). Comprehensive for an agent to use correctly given the complexity and lack of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description compensates fully: explains subject_prefix (LIKE delete), book_id (default), owner (omitted=logged in), and return value. Adds meaning beyond schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes lecture fragments under a subjectId prefix for an owner. It explains the LIKE delete behavior, effects on kgMindmap, and prefix length constraints, distinguishing it from other tools like save_lecture_frag and delete_questions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use guidance: warns against using a lesson-level prefix to retain the mindmap, notes BE forces prefix length >=9, and explains owner default. Does not name alternative tools but gives clear usage constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels: it discloses that only status='1' (published) questions are returned, drafts (status='0') never appear, non-numeric subject_id silently returns empty set, and the two different retrieval paths. It also explains the public vs private pool semantics and the subtree matching of subject_id. All behavioral traits are explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headers (🔴 sections for fast path, subject_id, public vs private) and a bulleted parameter list. It is front-loaded with the main purpose and endpoint. While it contains some verbose internal references (PRD-O-005) and emoji clutter, every sentence adds value and the organization aids readability. It is concise for the amount of detail provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (12 parameters, no annotations, output schema present), the description is remarkably complete. It covers tool purpose, all parameter semantics, two retrieval modes, public/private pool differences, return value format, error behavior (silent empty set), and filtering conditions. The output schema is described inline. An agent can correctly invoke the tool with this information alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate fully. It does: every parameter is explained with semantic meaning, including enumerations (e.g., question_type codes, difficult range 1-4, label_status values), usage context (e.g., page_index starts from 1, page_size default 20), and special behaviors (e.g., subject_id prefix subtree matching, batch_id/since for fast path). This is comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: paginated search of questions from the question bank, core for lesson preparation. It specifies the endpoint (POST /teacher/question/page) and return type ({ok, total, items}). It also distinguishes itself by describing two retrieval paths (fast recover with batch_id/since vs normal search), which differentiates it from siblings like get_question (single question retrieval) and my_recent_uploads (specialized recent uploads).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use alternative modes: it explains the fast recover path when batch_id or since is provided, and distinguishes between public pool (mine=False) and own questions (mine=True) with the note that '圈自己造的题必须 mine=True' (for self-created questions must use mine=True). It also explains the subject_id subtree matching behavior. However, it does not explicitly compare with all sibling tools, but the context is sufficient for most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses detailed behavioral traits: validation errors on missing fields, rejection of old fields, return format, and internal handling of binding fields. Since no annotations are provided, the description fully covers safety and mutability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed and well-organized with bullet points and sections, but somewhat verbose. Each sentence adds value, but could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: purpose, parameters, return value, validation, constraints, and references to business rules. Given the complexity and lack of formal output schema, the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% but the description provides exhaustive details for both 'plan' and 'lessons' parameters, including nested structures, required fields, types, and constraints. 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'create/modify course plan + batch upsert lessons in one step'. It uses specific verbs and resource, distinguishing it from siblings like 'get_plan_detail' or 'update_session'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisites (required target_type and target_id for new plans), warns about deprecated fields being rejected, and explains the concept of plans. Lacks explicit 'when not to use' alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: upsert semantics, image_map processing (replacement and removal with reporting), alignment guard, authentication requirement, and owner defaulting. The return format is also detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive, front-loading the core purpose and then systematically covering details in a structured paragraph with bullet points. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, nested objects, side effects), the description covers prerequisites, inputs, behavior, and return values. The output format is described in detail, compensating for the absent output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explains all 6 parameters in depth, including their purpose, mutual exclusivity, default values, and nested structure for frags items. This compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool is the sole entry point for upserting lecture fragments into the database, with a unique key for idempotency. It distinguishes itself from sibling tools like convert_lecture_docx (which produces the input) and remove_lecture_frag (which deletes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context: login prerequisite, mutual exclusivity of ir_path and frags, precedence of book_id from ir_path, and the allow_toc_fail flag. It does not explicitly compare to other tools for 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses all behavioral traits: side effects like triggering postponement for leave/cancel, distinction between soft and hard delete, and return values including deferred and overflow. No annotations provided, so description carries full burden and does so thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and headers, but slightly verbose. Could be more concise while retaining clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: actions, parameters, side effects, return values (deferred, overflow). Given 7 parameters and no annotations, the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond the schema: explains which parameters are used for which actions (e.g., date/start/end for reschedule, plan_lesson_id for rebind, note for note). Since schema coverage is 0%, description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it modifies a single session with specific actions (reschedule, leave, cancel, etc.), distinguishing it from siblings like schedule_sessions or list_schedule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Detailed guidelines for each action, including conditions, side effects, and when to use each, e.g., 'delete' is physical and irreversible, while 'cancel' is soft. Explicitly contrasts actions and their impacts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Details that only passed fields are updated, profile is overwritten entirely, and warns about clearing profile. No annotations, so description carries full burden; it does so comprehensively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose upfront, key warnings highlighted, and parameter list. Slightly long but justified by complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and output schema present in context, description covers return value, input constraints, and edge cases thoroughly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage but description provides detailed semantics for all parameters including required fields, data types, and special behaviors.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it updates teaching target records (student/class info) and explicitly distinguishes from sibling create_teach_target which only creates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use this tool vs create_teach_target and advises prerequisite step for profile updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral aspects: idempotency, parameter constraints (day positive integer, goals privacy rules), module pass-through, return format and error conditions. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized using bullet points and sections. It front-loads the core purpose and idempotency, then details parameters. While effective, it could be slightly more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, multiple module types, idempotency, privacy constraints), the description is thorough. It references relevant sibling tools, covers error handling, and specifies return values. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explains each parameter in depth: book_id sourcing, day semantics, goals content constraints, and modules structure with two types and their required fields (items vs qids). It 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to upsert the full content of a specific day into a check-in book, with idempotency. It distinguishes itself from sibling tools like list_punch_days and get_punch_day by focusing on creating/overwriting a day's content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool (for creating or updating a full day, including batch corrections), warns against fabricating book_id, and details the two module types with their respective handling. It implies alternatives for viewing or reviewing content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/RuntimeAll/teacher-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server