Create project materials via JSON or multipart requests, with optional files up to 20MB, first-version notes, and automatic WebP thumbnails for bitmap images.
创建资源。需 materials:manage 权限。支持 JSON 与 multipart 两种请求体；multipart 附带 file（可选，≤20MB，上传即创建版本 1）与 note（首版本备注），位图文件自动生成 WebP 缩略预览。 POST /api/projects/{id}/materials 项目由当前 API 密钥自动确定，无需传 projectId。
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the description's job is to add context, and it does: it discloses the required permission scope, the two supported request bodies (JSON vs multipart), the 20MB file cap, that upload auto-creates version 1, and that bitmaps get an auto-generated WebP preview. That is substantive behavioral detail beyond the annotations.
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-loads the core purpose and permission, then request-body details, then endpoint and project-scoping note. Dense but well-ordered with no padding; slightly heavy on multipart specifics for a one-parameter schema.
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 mutation tool with no output schema and a nested-object body at 0% schema coverage, the description covers permission, body formats, file limits and auto-project scoping. Gaps remain around the required JSON fields and what the response returns, so it is adequate but not fully complete.
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 0% (only the nested visibility field carries a description), so the description must compensate. It adds meaning for multipart fields (file ≤20MB, note, auto WebP preview) and the implicit project scoping, but it does not explain the actual JSON body fields the schema requires (typeId, name, description), so coverage is only partial.
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 ("创建资源" / create a material) and pins the exact endpoint POST /api/projects/{id}/materials, so the agent can distinguish it from siblings like anon_post_materials_types or anon_post_materials_resource_id_versions. It is clear but does not explicitly name those siblings to differentiate.
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?
Provides useful invocation context (requires materials:manage permission, project is auto-determined so no projectId is passed), which is real guidance. However it never states when to choose this tool over alternatives such as anon_post_materials_resource_id_versions for new versions, leaving the routing implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.