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

Beyond the annotations, the description richly discloses behavior: use the owner's original photos by default, require owner review of edited/generated images, do not generate images or bill for generation, and only mark photos_done after successful uploads and owner confirmation. This adds critical workflow context that annotations do not convey.

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 front-loads the core purpose and then adds necessary policy constraints. It is dense and somewhat long, but nearly every sentence carries meaningful guidance; a bulleted structure would improve scannability without changing 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?

Despite no output schema, the description explains what a no-argument call returns ('an upload widget where supported and upload_url as a fallback') and covers failure handling, cost disclosure, owner approval, and completion criteria. An agent has enough context to invoke the tool correctly and to handle follow-up steps responsibly.

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?

With 50% schema coverage, the description compensates well by explaining that 'files' are supported chat attachments and 'urls' are downloadable image links, and by constraining valid input ('never invent a URL or send a local file path'). It doesn't narrate draft_id and business_id, but those already have schema descriptions, so the overall parameter guidance is solid.

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 states a specific action and resource: 'Save photos for the business page' using files or urls. It also adds a clear role constraint ('Only for business owners signed in to Awning') and explains the tool can be called with nothing to receive an upload widget/fallback, which distinguishes it from generic upload tools.

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 explicitly says when to use the tool (owner photo uploads), when to use the fallback ('If attachments cannot be transferred, return the upload link'), and when to use other assistant tools ('Editing or image generation is optional...use the assistant's own image tools'). It also gives clear prohibitions: never invent a URL or send a local file path.

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