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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description reveals meaningful behavior: the server downloads and re-uploads URLs, files are accepted as base64, and the returned URLs are for internal use only. These details help the agent predict side effects and downstream usage. No contradiction with annotations is present.

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 compact and well-organized. The opening sentence states the purpose, the two modes are numbered clearly, and the crucial downstream instruction about passing mediaUrls to create_post is front-loaded. Every sentence contributes necessary information without redundancy.

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 description covers both parameter modes and the return flow, which is sufficient for basic invocation. However, given the sibling get_upload_urls, it omits explicit disambiguation about when to choose server-side upload_media versus generating upload URLs. It also does not mention constraints like file size limits or whether both urls and files can be provided together. These gaps make it adequate but not fully complete for an AI agent navigating the toolset.

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 already covers 100% of parameter descriptions, but the tool description adds value by explaining the behavioral distinction between the two modes: 'server downloads and re-uploads them' for URLs, and 'when the user attaches an image in the conversation' for files. This enriches the schema's otherwise structural definitions.

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 precise verb-resource statement: 'Upload media files for use in posts.' It then enumerates two concrete modes (URLs and base64 files), making the tool's purpose and scope explicit. The reference to returning mediaUrls for create_post further distinguishes it from sibling tools like get_upload_urls.

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 gives clear situational guidance for each mode: URLs for public media, base64 files for user-attached content. It also states the output should be passed to create_post and that the user should not see the returned URLs. However, it does not explicitly contrast with the sibling get_upload_urls or state when NOT to use this tool, leaving some ambiguity in tool selection.

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