upload_scene_image

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool automatically uploads and registers the image, and that it is free, which adds useful context beyond the schema. However, it does not mention side effects, whether an existing scene reference is replaced, auth requirements, or what the operation returns.

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 description is very concise and front-loaded, delivering the core purpose in the first sentence and then adding behavioral and cost details in short, separate clauses. No redundant or filler content is present.

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 simple two-parameter upload operation, the description covers the main action and registration behavior, but with no output schema and no annotations, it leaves the return value and success/failure semantics unexplained. It is adequate but not fully complete for an agent that may need to confirm the upload result.

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 50%: file_path has a description, but scene_id does not. The description only vaguely references '某场景' for scene_id and 'customer's own image' for file_path, without adding concrete semantic detail about the expected scene context or file requirements beyond what the schema already states.

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 clearly identifies the operation: using a customer-supplied image as the reference image for a scene, with automatic upload and registration. This distinguishes it from siblings like upload_shot_frame, upload_prop_sheet, and generate_scene_images by specifying the scene-reference purpose and customer-owned image source.

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 phrase '客户自有图片' implies this should be used when the customer already has their own image, as opposed to generating one. However, there is no explicit guidance about when not to use it or which sibling alternative to choose, such as generate_scene_images or quote_scene_images.

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