Read Moodle private messages: list conversations or fetch messages from a specific conversation without marking them as read. For forum content, use search_moodle_forum.
读取 Moodle 私信；无 conversation_id 列对话，有值则读该对话，且不会标已读。论坛内容用 search_moodle_forum。返回对话或消息。
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 数量上限；默认对话20、消息30 | |
| conversation_id | No | 对话 ID；省略=列对话 |
Changes observed during successful MCP inspections.
v0.1.4Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already declared, the description adds valuable context beyond annotations: that reading messages does not mark them as read, and that it returns conversations or messages depending on the input. It does not cover permissions, rate limits, or pagination, but the added behavioral detail is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise and front-loaded, starting immediately with the core purpose. Every sentence carries useful information, and there is no redundant or filler text.
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 simple two-parameter tool, no output schema, and existing readOnly annotation, the description covers all an agent needs: what it does, how the parameters affect behavior, when to use an alternative (forum), and what it returns. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter meanings are already fully documented in the schema. The description reiterates the conversation_id behavior (without it lists conversations, with it reads that conversation) but adds no new semantic details such as formats, constraints, or edge cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (读取/read) and resource (Moodle 私信/private messages), and explicitly distinguishes from the sibling search_moodle_forum by saying forum content should use that tool instead. It also clarifies the conditional behavior based on conversation_id, making the tool's scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit alternative for forum content (search_moodle_forum), which is the most likely source of confusion among siblings. However, it does not explicitly state when to use this tool versus other non-forum Moodle tools, nor does it mention prerequisites or exclusions beyond the forum case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.