upload_reference_image

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

Annotations only mark this as a non-readonly, non-idempotent, non-destructive open-world write. The description goes well beyond that, disclosing metadata stripping, a 5 MiB cap, login verification, the account-scoped reference_image_id, the possible side effect of a publicly retrievable OSS URL, and explicitly that an uncertain upload is never auto-retried.

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 purpose, then side effects and constraints in tightly packed sentences, with no filler. Minor redundancy between the source-directory phrase in sentence one and the 'requires a configured dedicated directory' sentence keeps it from a 5.

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 no output schema, the description correctly carries return and failure semantics (reference_image_id, no auto-retry) plus preconditions and side effects. The one real omission is disambiguation from the sibling upload_reference_media, which an agent genuinely needs before calling.

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?

The single parameter is fully documented in the schema (path inside TOPMEDIAI_UPLOAD_ROOT, no URLs/symlinks). The description still adds meaning by constraining accepted format (PNG/JPEG), the source directory concept, and a size limit, though it does not restate path syntax the schema already covers.

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+resource ('Upload a user-authorized local PNG/JPEG') and narrows scope to image-to-image or video first/last frames, which an agent can act on. However, it never distinguishes itself from the near-identical sibling upload_reference_media, so an agent faces an unresolved choice between the two.

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 states a prerequisite ('Upload requires a configured dedicated directory') and rules out an alternative action ('Does not generate or debit credits'), which implies context. But it gives no explicit when-to-use guidance and offers no routing versus upload_reference_media, leaving the primary selection decision to inference.

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