MK 拉取测验试卷

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

With no annotations at all, the description carries the full burden, and it does disclose one genuinely non-obvious behavior: the server DTO ships correct answers via option.answer=true and stdAnswer. It says nothing about auth requirements (the mk_login_* siblings imply a session is needed), failure modes for bad unitId/contentId, or whether the paper can be fetched repeatedly.

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?

A single front-loaded sentence with the return payload spelled out immediately; no filler. Slightly dense with DTO/option.answer jargon, but every clause carries information an agent needs.

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

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

For a 2-required-parameter read tool with no annotations and no output schema, the description covers the return payload well but leaves the parameter contract under-explained (unitId's meaning and its relation to contentId) and omits any auth or error context. Adequate to start a call, not sufficient to call confidently.

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

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

The description never mentions unitId or contentId, so it adds zero meaning beyond the schema. Coverage is only 50% — contentId carries a note tying it to the tid, but unitId is completely undocumented in both schema and description, and the description does nothing to close that gap.

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

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

States a specific verb and resource ('取随堂测验/考试试卷') and goes further by enumerating what comes back (题目、选项、正确答案), which separates it in practice from the write-side sibling mk_submit_quiz. It never names a sibling or explicitly contrasts with one, so it stays short of a 5.

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 trailing clause '可据此满分作答' implies this is the step before answering/submitting, but there is no explicit when-to-use, no statement that it is read-only and safe to call repeatedly, and no pointer to mk_submit_quiz as the follow-up action. Usage is inferable rather than stated.

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