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

With all annotation hints false, the description carries the burden and does so well: it discloses that the tool only creates a handoff, that persistence happens only after upload, and that the handoff is not proof of completion. It also warns against using the handoff to start generation or modify assets, adding safety context absent from annotations.

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 sentences, front-loaded with the use case, with each sentence adding non-redundant information: when to use, what it creates, and what not to infer from it. No filler or repetition of schema fields.

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 single-parameter tool with no output schema, the description gives enough behavioral context for invocation: what the tool returns (a handoff), what happens after upload, and how it connects to list_media. It could specify expiration duration or exact response shape, but these are minor for this level of complexity.

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 schema contains only 'kind' with an enum but no parameter descriptions (0% coverage). The description compensates by enumerating the accepted media kinds (image, video, audio) and tying them to the 'one private reference' use case, though it doesn't add much beyond restating the enum values.

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?

Description leads with 'Use this when the user needs to add one private reference,' giving a concrete verb and resource scope, and clarifies it produces a 'short-lived browser handoff' rather than the upload itself. This distinguishes it from sibling tools like import_reference_files or list_media by focusing on a single private reference upload.

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 opens with 'Use this when the user needs to add one private reference by requested media kind,' giving a clear trigger. It also provides negative guidance ('Do not use the handoff alone as proof that upload completed, to start generation, or to modify an existing asset'), though it does not name an alternative tool for those other jobs.

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