get_upload_token

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

With no annotations, the description carries the full burden and does well: it warns credentials are sensitive and must not appear in chat, logs, or command arguments; that rate limiting means do not re-upload; that pending/processing is not completion; and that recoveries must use the original operation_id. The opening sentence about preserving client_request_id is ambiguous and appears to belong to a different tool, which slightly muddies the picture.

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 purpose sentence is not front-loaded; it is preceded by unrelated-looking clauses about client_request_id and task states, and the warning emoji line is appended at the end. Several sentences do not clearly belong to a credential-issuing tool, so the reader must filter to find the operative content.

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 parameterless-required credential tool with no output schema, the description covers the essential pieces: what is returned, how to use the token (multipart/form-data POST), the follow-up step (save_note with image_id), and two failure modes (mime_type mismatch, rate limiting). Missing is any hint about credential lifetime or whether tokens are single-use.

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 coverage is 100%, so the baseline is 3; the description earns an extra point by adding a real constraint the schema does not state — mime_type must match the actual file format or the OSS signature will fail. It adds nothing new for count or operation_id beyond the schema text.

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 core statement '获取 OSS 图片上传凭证' with the returned fields (accessid/host/policy/signature) is specific and actionable, but it appears mid-way through the description after several sentences about client_request_id preservation, rate limits, and task states that read like guidance copied from another tool. It never contrasts itself with the close siblings upload_image or get_knowledge_file_upload_token.

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 does supply a workflow (upload via multipart/form-data, get image_id, then call save_note) and recovery rules (reuse original operation_id, no new key). However, it gives no explicit rule for choosing this tool over the nearly identical siblings upload_image and get_knowledge_file_upload_token, which is the main decision an agent faces.

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