Lists material versions by resource ID, sorted by version number descending, for project members with visibility access; the API key determines the project.
列出版本。项目成员且通过可见范围校验。按版本号倒序。 GET /api/projects/{id}/materials/{resourceId}/versions 项目由当前 API 密钥自动确定，无需传 projectId。
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds real context beyond them: the visibility/auth precondition, the descending-version-number sort order, and the fact that the project is derived from the API key. Sort order and the auto-scoped project are non-obvious behaviors not encoded in the schema.
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?
Front-loaded with the action word, then constraints in terse fragments with no filler. Every sentence carries information; the endpoint line is the only mildly redundant element given the name already encodes the path.
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?
No output schema exists, and the description compensates by stating the ordering of returned versions and the auth/visibility gate. Missing pagination behavior and any return-field detail keeps it from full completeness, but it covers what an agent needs to invoke it correctly.
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?
One parameter at 0% schema description coverage; the description clarifies the project need not be passed (it comes from the API key), which is useful negative guidance. But it never explains the single path.resourceId parameter's meaning or format, so the schema's only parameter remains semantically thin.
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 ('列出版本' / list versions) and pins the exact endpoint, making it distinguishable from the write sibling anon_post_materials_resource_id_versions and the download/preview variants. It does not explicitly name those siblings, so it stops short of the top mark.
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 gives a prerequisite ('项目成员且通过可见范围校验' – must be a project member passing visibility scope), which is genuine usage context. However it never states when to prefer this over the version_download or version_preview siblings, leaving the choice implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.