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

The annotations declare readOnlyHint=true, but the description states the tool attaches files into a page's file input and writes blobs to /tmp — both environment mutations, so the description's disclosed behavior contradicts the read-only annotation. This is a real inconsistency an agent could be misled by, even though the 25MB cap and /tmp destination are otherwise useful behavioral detail.

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?

Three tight sentences: purpose first, then the parameter-choice rule, then the hard constraint. No filler, and each sentence adds information an agent needs.

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 5-parameter browser tool with no output schema, the description covers mechanism, both input modes, and the size limit. It stops short of explaining how `page_id`/`ref` are obtained or what happens on the page after attachment, but no return-value documentation is required since no output schema exists.

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 20% (just `in_workspace`), so the description must carry the load and largely does: it explains that `local_paths` are absolute host paths and that `data` items are {name, mime, base64} blobs staged in /tmp, plus a size cap absent from the schema. It adds nothing for `ref` or `page_id`, which remain unexplained in both places.

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 ('Attach files') and an exact target ('an <input type=file>'), which cleanly separates it from storage-oriented siblings such as files_upload, collections_add_file, and agents_add_file. The mechanism (browser DOM file input) is unambiguous from the description alone.

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?

Usage is only implied by the mention of a file input; there is no explicit when-to-use/when-not and no alternative is named. It does explain the two mutually exclusive input modes and the 25MB cap, but omits prerequisites such as needing an open page and a `ref` obtained from browser_snapshot.

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