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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the mutation profile is covered. The description adds genuinely new behavioral facts: a 20 MiB size ceiling, the accepted formats, and the reassurance that this neither generates media nor spends generation credits — all decision-relevant for an agent choosing between uploading and generating.

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?

Five short sentences, front-loaded with what it does, then routing guidance, then constraints. Nothing is repeated from the schema or annotations verbatim, and every sentence carries either a routing decision or a constraint.

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?

An output schema exists, yet the description still tells the agent what the return value is for (feed file_path to a generation tool), which is the piece an agent most needs to chain calls. Combined with size limits, format restrictions, and credit-cost disclaimers, nothing required to invoke and follow on correctly is missing.

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 already 100% with a well-documented nested image object, so the baseline is 3. The description still adds meaning the schema lacks: a one-image limit and a 20 MiB cap, plus the note that file_path is what flows into the next tool, which reinforces why the full file object (not a bare ID) is required.

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 (uploads), specific resource (a ChatGPT-attached image), accepted formats (PNG/JPEG/WebP) and destination (connected Magic Hour account). It also explicitly carves itself out from get_upload_urls and from generation tools, so an agent can distinguish it from siblings without opening a schema.

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?

Gives explicit when-to-use ('native ChatGPT photo attachments') and names the alternative path it replaces (having the file runtime PUT bytes to get_upload_urls), plus the downstream step of passing file_path to a generation tool. The one gap is that the sibling upload_chatgpt_media is never mentioned, so the agent must infer the split between image and other media uploads.

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