safari_upload_file

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

No annotations are provided, so the description carries the full disclosure burden — and it is exceptionally candid. It discloses that the tool will close an open file dialog first, that 'verified 0 files' may appear even on success with custom upload handlers, and that some sites (Google Business Profile) accept the file handle but ingest nothing, causing the post to publish with no image. It also reveals the verifyPreview escalation behavior to a real OS dialog. This is model behavioral disclosure.

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 long (~120 words) but every element earns its place — the don't-click warning, the verification caveat, and the concrete Google Business Profile bug are all operationally essential. The key directive is front-loaded, with edge cases following. Dense but not bloated; the length is justified by the tool's complexity.

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 complex synthetic-injection tool with no output schema and full schema coverage, the description is nearly complete: it covers the action, prerequisites, failure modes, verification behavior, and escalation path. The only minor gap is that the exact return format is not specified beyond the 'verified 0 files' note, but with no output schema declared, the description is more than sufficient for correct invocation.

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 100%, so the baseline is 3. The description adds genuine value beyond the schema: the Google Business Profile failure case explains why verifyPreview exists, and the forceNative path's need for 'an unlocked screen and briefly focuses Safari' is stated in the description. This elevates the parameter guidance above the schema baseline.

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, and mechanism: 'Upload a file to a <input type='file'> element via JavaScript DataTransfer.' The 'NO file dialog, NO UI interaction' framing explicitly differentiates it from any native/UI-driven interaction, and the synthetic-vs-native mechanism distinguishes it from related siblings like safari_native_type or safari_paste_image. No ambiguity about what this tool does.

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 how-to-use directives: 'Do NOT click the file input before calling this tool — just provide the selector and file path,' plus when to pass verifyPreview (images into a composer) and when to use forceNative ('Use when the site is known to reject synthetic uploads'). It does not explicitly name alternative tools for exclusion cases, but the conditional guidance for the flag parameters is concrete and actionable.

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