upload_image

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

With no annotations, the description carries the burden of behavioral disclosure. It adds meaningful context beyond the schema: supported image formats (PNG, JPG, GIF), the return value (image URN), and the critical two-step upload flow (initialize upload, then upload binary). This gives an agent a realistic model of how the operation behaves. It does not mention size limits or permission requirements, but the disclosed two-step behavior is substantial.

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 three sentences with no filler. It front-loads the core purpose, then covers format support, output usage, and the two-step process in a logical order. Every sentence contributes essential information for correct invocation.

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?

The tool has no output schema and no annotations, so the description must explain the return contract and operational behavior. It does: the image URN is returned for use as mediaId, and the upload is a two-step process. It does not mention failure modes, file size limits, or accountId/assetName implications, but those are either covered by the schema or less critical than the two-step flow and URN output.

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 input schema already has 100% description coverage for all four parameters, so the baseline is 3. The tool description adds context by explaining the output URN's role and the upload flow, but it does not add new meaning to individual parameters beyond what the schema already provides. This is acceptable given the schema's completeness.

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 opens with a specific verb and resource: 'Uploads an image file to LinkedIn for use in ads.' It clearly explains the purpose and distinguishes this from sibling tools like create_inline_ad by specifying that this tool produces the image URN used as mediaId. The intended role in the ad-creation flow is unmistakable.

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?

The description states when this tool is relevant: before creating inline ads, because it returns the image URN to use as mediaId. It does not explicitly name alternatives or state when not to use it, but the connection to inline ad creation provides clear contextual guidance along with the sibling tool create_inline_ad.

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