List and flatten a course's materials, then filter by type, free status, name or description, and sort by newest, oldest, popularity, or name.
展平课程资料，支持资料类型、免费、名称/描述筛选与最新/最旧/热门/名称排序。
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | newest | |
| query | No | ||
| course_id | Yes | 平台对象 ID，正整数 | |
| free_only | No | ||
| max_results | No | ||
| material_type_id | No |
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds only the implicit hint that results are 'flattened', which is mildly useful context for the returned shape, but it omits pagination/limit behavior and scope beyond the filters listed.
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?
One compact sentence with zero filler, and the core capability is front-loaded. It is slightly under-specified rather than verbose, which is the lesser problem here.
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 an output schema and annotations present, the description needn't explain return values or safety, and it covers most filters. But for a 6-parameter, list-style tool with a max_results cap of 300 and no differentiation from sibling listing tools, an agent is left with meaningful gaps about scope and limits.
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 only 17%, so the description must carry the load: it explains that query filters by name/description and maps material type, free-only, and the four sort modes, which meaningfully compensates for the undocumented query parameter. It still leaves course_id and max_results (the 300 cap) undescribed.
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 resource (课程资料/course materials) and enumerates the supported filter and sort dimensions, so the operation is clear. However, it does not distinguish this listing tool from close siblings such as share_get_course_materials, share_search_materials, or share_list_my_uploads, and the term '展平' (flatten) is unexplained.
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 never states when to use this tool rather than the sibling material-listing or material-search tools. The filter/sort enumeration implies a browsing use case but leaves the agent to infer routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.