Get media URLs

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

The annotations already declare readOnlyHint=true, and the description does not contradict this. It adds useful behavior beyond the annotations by specifying the input key format and the two exact output fields, which helps an agent understand what the lookup returns. No destructive or auth-related surprises are disclosed or hidden.

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 one tightly written sentence with the action front-loaded and an illustrative example included. There is no filler, and every clause contributes to understanding the tool's function.

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 low-complexity tool with two required parameters, no nested objects, and annotations covering read-only safety, the description is largely sufficient. It names the returned fields despite the lack of an output schema. A minor gap is that it does not mention how invalid or missing media keys are handled, but this is not critical for basic 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 50%: account_id is well described in the schema, while media_keys has no schema description. The description compensates partially by explaining that media_keys are media_key values and giving an example, but it does not clarify array behavior or the relationship between media_url and poster_media_url. This is adequate but not thorough.

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 uses a specific verb ('Resolve') with a concrete resource ('Media Library') and names the output fields ('media_url / poster_media_url'). This clearly sets it apart from sibling getters like x_ads_get_tweets or x_ads_get_cards, which target different resources.

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 implies the usage context: call this when you have media_key values and need their URLs. However, it does not explicitly state when not to use it or mention an alternative tool, such as x_ads_upload_media or a media listing tool, so the guidance is inferred rather than explicit.

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