This server provides a read-only interface for teachers to query Moodle student data via the DAMI Robot API, secured by strict speaker authorization and context isolation. It supports no write or administrative actions.
Test Connection: Verify connectivity to the DAMI Moodle Robot API without requiring speaker authorization.
Find Student: Locate a student by name, email, user ID, and optionally filter by course/group; supports disambiguating duplicate names.
Get Student Summary: Retrieve an overview of a student's academic status, including attendance, missing homework, suspension status, latest scores, and DAMI level/EXP.
Get Student Attendance: Fetch attendance records, including absences, lateness, warnings, and recent attendance history.
Get Missing Homework: List missing or incomplete online assignments.
Get Student Suspend Status: Check whether a student is suspended, locked, on hold, or at risk of being locked.
Get Student DAMI Status: View diligence points, study hours, streak, EXP, level, energy, and ranking.
Get Student Latest Scores: Get recent section scores (e.g., Listening/Reading, Speaking, Writing), including strengths and weaknesses.
Get Student Fulltest History: View full test/LR performance history, recent tests, and score trends.
Get Student Goal Status: Show target score, exam date, progress toward the goal, and whether it has been achieved.
Get Course Risk Students: Identify at-risk students in a course/group based on missing homework, low diligence, or potential suspension.
Provides tools to query student data from Moodle, including summaries, attendance, homework, status, and risk analysis via the local_damirobot_api plugin.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@DAMI Robot MCP Server check attendance for student 42"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Zero-dependency MCP STDIO server for Xiaozhi/imcp. This version does not use @modelcontextprotocol/sdk, so it is lighter and easier for hosted MCP gateways to run from GitHub with npx.
Mode: STDIO
Command: npx
Arguments:
-y
--package
github:trantuandat0305/damirobot-mcp-server
damirobot-mcp-serverIf the gateway still cannot load schemas, try the shorter argument form:
-y
github:trantuandat0305/damirobot-mcp-serverEnvironment variables:
VOICE=1
MOODLE_BASE_URL=https://elearning.anhngumsmy.com
DEFAULT_COURSEID=4
MOODLE_API_TOKEN=PUT_YOUR_TOKEN_HERE
REQUEST_TIMEOUT_MS=15000
MOODLE_TOOL_ENDPOINT=https://elearning.anhngumsmy.com/local/damirobot_api/api/tool.php
# Optional stricter whitelist.
# Leave empty to allow any non-empty speakerId produced by Xiaozhi voiceprint recognition.
# Example: ALLOWED_SPEAKER_IDS=id_1,id_2
ALLOWED_SPEAKER_IDS=Related MCP server: Moodle MCP Server
All student-data tools are mandatory fail-closed before Moodle is called.
Missing/null/invalid speakerId: denied.
Sentinel values such as null, undefined, unknown, anonymous, guest, none: denied.
speakerId must come from Xiaozhi top-level params.speakerId; _meta.speakerId is accepted as fallback.
arguments.speakerId is deliberately ignored, so the LLM/tool arguments cannot grant access to themselves.
When ALLOWED_SPEAKER_IDS is empty, any valid Xiaozhi-recognized speakerId is accepted. This supports adding a new registered speaker without firmware changes or MCP code changes.
When ALLOWED_SPEAKER_IDS is configured, only exact IDs in that list are accepted.
test_connection remains available without speaker recognition because it exposes no student data.
There is no environment-variable bypass for the student-data guard.
The MCP server tracks the current recognized speaker so follow-up questions can work safely.
Same authorized speakerId: student follow-up context may be reused.
Different authorized speakerId: student/course/group follow-up context is cleared before the next data call.
Missing/denied speaker: all speaker-bound context is cleared.
This prevents a later speaker from inheriting the previous speaker's selected student.
npm run check
npm testThe regression suite verifies fail-closed behavior, argument spoof rejection, malformed speaker IDs, optional explicit allowlists, speaker-switch context isolation, same-speaker follow-up context, and the non-sensitive test_connection exception.
GitHub Actions runs these checks on pushes and pull requests to main.
test_connection
find_student
get_student_summary
get_student_attendance
get_missing_homework
get_student_suspend_status
get_student_dami_status
get_student_latest_scores
get_student_goal_status
get_student_fulltest_history
get_course_risk_students
Student-data tools require an authorized Xiaozhi speaker identity.
Read-only: only calls the Moodle DAMI Robot API.
Does not write, update, delete, suspend, check-in, or feed DAMI.
No token is stored in code. Put token only in environment variables.
Tìm học viên theo tên/email/userid và lớp/course/group. Dùng khi giáo viên vừa nhắc tên học viên hoặc khi cần phân biệt trùng tên.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email/username học viên nếu cần phân biệt trùng tên. | ||
| userid | No | Moodle user ID. Nên dùng khi đã biết để tránh trùng tên. | |
| groupid | No | Moodle group ID nếu biết. | |
| courseid | No | Moodle course ID. Nếu bỏ trống sẽ dùng DEFAULT_COURSEID. | |
| group_name | No | Tên group/cohort nếu cần lọc trong lớp. | |
| course_name | No | Tên lớp/course trong Moodle. | |
| student_name | No | Tên học viên, có thể là tên đầy đủ hoặc tên thường gọi. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It omits whether the operation is read-only, destructive, or any other behavioral aspects like rate limits or side effects. The description only focuses on use cases. Grade: 2 (does not disclose behavioral traits beyond annotations; significant gap for a search tool).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no extraneous content. Every word contributes to clarity. Grade: 5 (appropriately sized and front-loaded).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters and no output schema or annotations, the description is incomplete. It does not explain return format, handling of multiple matches, or default behavior (e.g., DEFAULT_COURSEID mentioned in param but not explained). It covers when to use but not what to expect. Grade: 3 (adequate but with clear gaps given complexity).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the tool description adds little beyond grouping parameters into categories. The schema already documents each parameter's purpose. The description does not provide additional semantics or clarify parameter relationships beyond what the schema offers. Grade: 3 (baseline for high schema coverage, no added meaning).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds students by name, email, userid, and class/course/group. It distinguishes from sibling tools that retrieve specific student data. Grade: 5 (specific verb+resource, distinguishes from siblings).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies usage scenarios: when a teacher just mentions a student name or needs to distinguish duplicate names. This provides clear context, though it doesn't explicitly mention when not to use or alternatives. Grade: 4 (clear context, no exclusions).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dùng khi hỏi trong lớp/course có ai rủi ro, ai thiếu bài, ai chăm chỉ thấp, ai sắp bị đình chỉ hoặc cần nhắc nhở.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Số học viên tối đa trả về. | |
| groupid | No | Moodle group ID nếu biết. | |
| courseid | No | Moodle course ID. Nếu bỏ trống sẽ dùng DEFAULT_COURSEID. | |
| group_name | No | Tên group/cohort nếu cần lọc trong lớp. | |
| course_name | No | Tên lớp/course trong Moodle. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must explain behavior. It states what kind of risk information is returned but does not mention read-only nature, side effects, or authentication. It is sufficient as a query tool description but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence in Vietnamese that is concise and front-loaded. It uses no unnecessary words and directly conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description does not explain return format or ordering. Five optional parameters imply flexible queries, but the description is brief. It covers the essential use cases but is not fully detailed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so each parameter is already documented. The tool description does not add additional meaning or context beyond what the schema provides. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose in Vietnamese: identifying at-risk students, missing assignments, low effort, pending suspension, or needing reminders. The verb 'get' is implied and it distinguishes from sibling tools like 'get_missing_homework' which is more specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates usage when asking about risk students in a course. It does not explicitly state when not to use or mention alternatives, but the sibling tools provide context. This is clear enough for basic guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dùng khi hỏi học viên còn thiếu bài/nợ bài/chưa làm bài online nào. Không dùng cho câu hỏi thiếu bao nhiêu điểm.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email/username học viên nếu cần phân biệt trùng tên. | ||
| userid | No | Moodle user ID. Nên dùng khi đã biết để tránh trùng tên. | |
| groupid | No | Moodle group ID nếu biết. | |
| courseid | No | Moodle course ID. Nếu bỏ trống sẽ dùng DEFAULT_COURSEID. | |
| group_name | No | Tên group/cohort nếu cần lọc trong lớp. | |
| course_name | No | Tên lớp/course trong Moodle. | |
| student_name | No | Tên học viên, có thể là tên đầy đủ hoặc tên thường gọi. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the tool's purpose without disclosing behavioral traits such as side effects, read-only nature, required permissions, or error conditions. The agent lacks information about safety and expected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose and usage guidelines. Every word adds value, with no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal: no output schema exists, and the description does not explain return values, data format, or how results are structured. Given 7 parameters and no annotations, the description lacks completeness for an agent to fully understand the tool's response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter having a description. The tool description does not add further meaning beyond the schema, but the schema itself is adequate. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The name and description clearly indicate the tool is for retrieving missing homework assignments, and it explicitly excludes missing points, which distinguishes it from a potential related query. However, it doesn't specify the exact output format (e.g., list of assignments) or distinguish from siblings like get_student_summary that might also include missing homework.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('missing homework') and when not to use ('not for missing points'). It provides clear context but does not name an alternative tool for the excluded case, though siblings do not directly cover missing points.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dùng khi hỏi điểm danh, đi học, nghỉ/vắng, trễ, cảnh báo C/D, nghỉ buổi nào hoặc lịch sử điểm danh gần đây của học viên.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email/username học viên nếu cần phân biệt trùng tên. | ||
| limit | No | Số bản ghi gần đây cần xem, ví dụ 10. | |
| userid | No | Moodle user ID. Nên dùng khi đã biết để tránh trùng tên. | |
| groupid | No | Moodle group ID nếu biết. | |
| courseid | No | Moodle course ID. Nếu bỏ trống sẽ dùng DEFAULT_COURSEID. | |
| group_name | No | Tên group/cohort nếu cần lọc trong lớp. | |
| course_name | No | Tên lớp/course trong Moodle. | |
| student_name | No | Tên học viên, có thể là tên đầy đủ hoặc tên thường gọi. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description does not disclose any behavioral traits (e.g., read-only, side effects, authentication needs). It only describes the purpose, leaving agents unaware of operational characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that gets straight to the point, front-loading the purpose with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 8 optional parameters and no output schema, the description does not explain how parameters interact, default behavior, or what the return data looks like, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so individual parameter descriptions exist. The tool description does not add extra semantics beyond the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly lists specific use cases (attendance, absences, tardiness, warnings, recent history) and uses a verb that relates to querying, distinguishing it from sibling tools which cover different student data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('Dùng khi hỏi...' i.e., 'Use when asking about...'), providing clear context. However, it does not mention when not to use it or direct replacements among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dùng khi hỏi điểm chăm chỉ/chuyên cần, giờ học, ngày học, streak, EXP, level DAMI, energy hoặc xếp hạng của học viên.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email/username học viên nếu cần phân biệt trùng tên. | ||
| userid | No | Moodle user ID. Nên dùng khi đã biết để tránh trùng tên. | |
| groupid | No | Moodle group ID nếu biết. | |
| courseid | No | Moodle course ID. Nếu bỏ trống sẽ dùng DEFAULT_COURSEID. | |
| group_name | No | Tên group/cohort nếu cần lọc trong lớp. | |
| course_name | No | Tên lớp/course trong Moodle. | |
| student_name | No | Tên học viên, có thể là tên đầy đủ hoặc tên thường gọi. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It does not mention whether the operation is read-only, any required permissions, side effects, rate limits, or the structure of the response. For a query tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded with the trigger phrase 'Use when asking about', but for a tool with 7 optional parameters, it could benefit from slightly more structure to guide parameter selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 7 optional identifiers, no output schema, and no annotations, the description is incomplete. It does not explain how identifiers interact (e.g., which combination is needed, fallback behavior), what the response contains, or how to handle ambiguous inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all 7 parameters. The description does not add extra meaning beyond the schema, so it meets the baseline but does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly lists the specific data points (attendance points, study hours, streak, EXP, etc.) that the tool retrieves, making its purpose evident. However, it could be more explicit by including a verb like 'retrieve' or 'get', and it does not distinguish itself from sibling tools like get_student_attendance, which may overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use the tool ('Use when asking about...'), implying the context, but it does not provide guidance on when not to use it or which sibling tools are alternatives, leaving the agent to infer the boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dùng khi hỏi lịch sử FULL TEST/LR, các bài FULL TEST gần nhất, 3-5 bài gần đây, điểm tăng hay giảm, xu hướng điểm hoặc tiến bộ qua các FULL TEST.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email/username học viên nếu cần phân biệt trùng tên. | ||
| limit | No | Số bài FULL TEST/LR gần nhất cần xem, mặc định 5. | |
| userid | No | Moodle user ID. Nên dùng khi đã biết để tránh trùng tên. | |
| groupid | No | Moodle group ID nếu biết. | |
| courseid | No | Moodle course ID. Nếu bỏ trống sẽ dùng DEFAULT_COURSEID. | |
| group_name | No | Tên group/cohort nếu cần lọc trong lớp. | |
| course_name | No | Tên lớp/course trong Moodle. | |
| student_name | No | Tên học viên, có thể là tên đầy đủ hoặc tên thường gọi. |
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 only states the purpose and does not disclose behavioral traits like read-only nature (implied but not stated), authentication requirements, rate limits, or side effects. The description adds minimal transparency beyond the purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence in Vietnamese that front-loads the usage context. It covers the key purposes without unnecessary words, though it could be structured to better separate different use cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 optional parameters and no output schema. The description does not explain what the output contains (e.g., list of tests with scores, trends), how parameters interact (e.g., when multiple identifiers are provided), or handle edge cases. More context is needed for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 8 parameters have descriptions in the schema (100% coverage). The tool description provides overall context but does not add extra semantics for parameters beyond what is in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for querying FULL TEST/LR history, recent tests, score trends, and progress. It uses specific verbs like 'hỏi' (ask) and 'xem' (view) and specifies the resource. While it doesn't explicitly differentiate from siblings like get_student_latest_scores, the focus on history and trends distinguishes it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description begins with 'Dùng khi hỏi...' (Use when asking about...), providing clear usage context. However, it does not mention when not to use this tool or suggest alternatives, such as when only latest scores are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dùng khi hỏi mục tiêu điểm thi, ngày thi, còn thiếu bao nhiêu điểm để đạt mục tiêu, đã đạt mục tiêu chưa hoặc tiến độ mục tiêu của học viên.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email/username học viên nếu cần phân biệt trùng tên. | ||
| userid | No | Moodle user ID. Nên dùng khi đã biết để tránh trùng tên. | |
| groupid | No | Moodle group ID nếu biết. | |
| courseid | No | Moodle course ID. Nếu bỏ trống sẽ dùng DEFAULT_COURSEID. | |
| group_name | No | Tên group/cohort nếu cần lọc trong lớp. | |
| course_name | No | Tên lớp/course trong Moodle. | |
| student_name | No | Tên học viên, có thể là tên đầy đủ hoặc tên thường gọi. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It indicates the tool returns goal-related information (scores, dates, progress), but lacks details on whether it is read-only, any side effects, rate limits, or consistency guarantees. The description is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose. It is not overly verbose, though it could be slightly more concise by removing redundant phrasing. Still, it earns its place with clear intent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 optional parameters, no output schema, and no annotations, the description covers the main use cases thoroughly. It explains what information the tool provides, which compensates for the lack of output schema. However, it misses details on return format or behaviors like pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 7 parameters are fully described in the input schema (100% coverage). The description adds no additional semantics beyond the schema; it only states the overall purpose. Baseline 3 is appropriate as the schema already provides meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for querying student goal status, including test score goals, test dates, progress, and whether the goal is achieved. This verb+resource combination is specific and distinguishes it from sibling tools, none of which explicitly target goals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('Dùng khi hỏi...' meaning 'Use when asking...'), providing clear context. However, it does not mention when not to use it or suggest alternative tools, leaving room for improvement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dùng khi hỏi điểm gần nhất, điểm LR/Speaking/Writing, full test mới nhất, phần/part yếu nhất, phần/part mạnh nhất của học viên.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email/username học viên nếu cần phân biệt trùng tên. | ||
| userid | No | Moodle user ID. Nên dùng khi đã biết để tránh trùng tên. | |
| groupid | No | Moodle group ID nếu biết. | |
| courseid | No | Moodle course ID. Nếu bỏ trống sẽ dùng DEFAULT_COURSEID. | |
| group_name | No | Tên group/cohort nếu cần lọc trong lớp. | |
| course_name | No | Tên lớp/course trong Moodle. | |
| student_name | No | Tên học viên, có thể là tên đầy đủ hoặc tên thường gọi. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description does not disclose behavioral traits (read-only, auth, rate limits, side effects). It only describes functionality, not how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is one sentence with multiple clauses, conveying purpose without fluff. Though a bit run-on, it is efficient and front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 optional parameters and no output schema, description does not guide parameter selection or specify return format. Lacks info on how to identify the student or handle empty results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already documented. Description adds no extra meaning beyond listing tasks; it does not clarify parameter interaction or recommended usage patterns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly lists specific tasks: latest scores, LR/Speaking/Writing scores, latest full test, weakest/strongest parts. This distinguishes it from siblings like get_student_fulltest_history which focuses on history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description states 'use when asking about...' implying context but does not explicitly exclude other tools or mention alternatives. For example, it could note to use get_student_fulltest_history for non-latest tests.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dùng khi giáo viên hỏi tổng quan/tình hình học tập của một học viên: điểm danh, bài thiếu, đình chỉ/bảo lưu, điểm gần nhất, DAMI level/EXP.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email/username học viên nếu cần phân biệt trùng tên. | ||
| userid | No | Moodle user ID. Nên dùng khi đã biết để tránh trùng tên. | |
| groupid | No | Moodle group ID nếu biết. | |
| courseid | No | Moodle course ID. Nếu bỏ trống sẽ dùng DEFAULT_COURSEID. | |
| group_name | No | Tên group/cohort nếu cần lọc trong lớp. | |
| course_name | No | Tên lớp/course trong Moodle. | |
| student_name | No | Tên học viên, có thể là tên đầy đủ hoặc tên thường gọi. |
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 lists what categories of data are covered but does not disclose behavioral traits such as required permissions, data recency, or behavior when data is missing. For a composite tool, more detail would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the core purpose and scope without any wasted words. It is front-loaded with the use case and immediately lists the covered areas.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 optional parameters and no output schema, the description does not explain the return format, how parameters interact, or default behavior. It covers what data is returned but lacks details needed for full understanding of tool behavior in various scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add extra meaning beyond what is in the schema; it merely lists the categories of output. Parameters are adequately documented in the schema but the description provides no additional semantic guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: providing an overview of a student's learning status including attendance, missing assignments, suspension/retention, latest scores, and DAMI level/EXP. It is a specific verb+resource combination that distinguishes from sibling tools which focus on individual aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use when teachers ask for overview/learning status,' providing clear context. However, it does not mention when not to use or explicitly list alternatives, though sibling tools are available for specific queries. The usage guidance is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dùng khi hỏi học viên có bị đình chỉ, khóa nick, bảo lưu, vi phạm, chờ xóa hoặc nguy cơ bị khóa chưa.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email/username học viên nếu cần phân biệt trùng tên. | ||
| userid | No | Moodle user ID. Nên dùng khi đã biết để tránh trùng tên. | |
| groupid | No | Moodle group ID nếu biết. | |
| courseid | No | Moodle course ID. Nếu bỏ trống sẽ dùng DEFAULT_COURSEID. | |
| group_name | No | Tên group/cohort nếu cần lọc trong lớp. | |
| course_name | No | Tên lớp/course trong Moodle. | |
| student_name | No | Tên học viên, có thể là tên đầy đủ hoặc tên thường gọi. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It explains the tool checks for specific statuses, which is helpful. However, it does not state whether it is a read-only operation, any side effects, or required permissions. The behavioral insight is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the usage context. Every word earns its place, and there is no wasted information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details about the output format or structure. With no output schema, the agent does not know what the tool returns (e.g., a boolean, a list of statuses). The complexity of 7 parameters is not fully addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The parameter descriptions in the schema are already detailed (email, userid, etc.). The tool description does not add significant meaning beyond the schema, though it lists the statuses checked.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks if a student is in various restrictive states like suspended, locked, reserved, etc. It uses a specific verb-resource combination and distinguishes itself from sibling tools that cover other aspects (e.g., attendance, summary).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly starts with 'Dùng khi' (Use when), providing a clear usage context. However, it does not mention when not to use this tool or suggest alternatives, which would further improve guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Kiểm tra kết nối từ Xiaozhi/imcp MCP server tới DAMI Moodle Robot API. Chỉ dùng để test kỹ thuật.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It indicates a non-destructive test operation but does not detail the exact behavior, such as return values or success/failure indicators. Adequate but lacks specificity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. The first states the purpose, the second provides usage guidance. No extraneous words; front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description is mostly complete. It states the purpose and use context. Could be improved by mentioning the expected response format, but not essential for a simple test tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description adds no parameter info but none is needed. Baseline 4 applies due to zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks connectivity from the MCP server to the DAMI Moodle Robot API, specifying it is for technical testing. It distinguishes itself from sibling tools which are all data retrieval operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Chỉ dùng để test kỹ thuật' (only for technical testing), providing clear context on when to use. No alternatives are needed since no other 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0find_studentget_course_risk_studentsget_missing_homeworkget_student_attendanceget_student_dami_statusget_student_fulltest_historyget_student_goal_statusget_student_latest_scoresget_student_summaryget_student_suspend_statustest_connectionScored across 11 tools
Each tool targets a distinct aspect of student data (e.g., attendance, scores, risk, suspensions). Descriptions are specific and clearly delineate when to use each, minimizing ambiguity.
All tools follow a consistent verb_noun pattern with snake_case (e.g., get_student_attendance, find_student). The 'find_' variant is acceptable as it differs only in retrieval style.
With 11 tools, the set covers the core student information needs without being excessive. Each tool serves a clear purpose within the educational domain.
The tools cover most common queries (attendance, scores, goals, risk, suspensions, summary). Missing a generic 'list students in course' tool, but the set is otherwise well-rounded for a read-only assistant.
Connect your Moodle to AI assistants: courses, content, grading and reports from the chat.
Search university course materials, your flashcards, quizzes, streak and quota. All tools read-only.
Read-only IELTS and CELPIP question banks, learner practice, progress, scores, and feedback.
Read-only access to your own Pithflow meeting notes, transcripts, dictionary and usage.