Get media

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

Annotations only cover readOnlyHint and openWorldHint, and the description adds substantial behavior the annotations cannot: preview links expire after one hour, previews are only present once a picture is 'ready', and readiness takes seconds for images versus up to a minute for video. That is exactly the operational context an agent needs to avoid treating an empty preview as an error.

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 purpose is front-loaded, but the middle sentence is a long run-on covering preview shape enumeration, TTL, and crop guidance, and the phrasing ('for a picture that is ready previews') is grammatically awkward. All the content earns its place, but the structure makes it harder to parse than it needs to be.

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?

There is no output schema, and the description compensates well by enumerating the returned fields: a time-limited link with width and height per stored shape. It is only slightly incomplete in not stating what is returned for videos or for files that are not yet ready.

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 coverage is 0%, so the description must carry the meaning of mediaId, and it does partially by framing it as an id of a file 'as postfjord_list_media shows it' — implying where ids come from. It does not restate the id format or validated pattern, which is left entirely to the schema.

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 and resource ('One file in the media library by id') and clarifies the returned shape relative to postfjord_list_media. It also explicitly distinguishes itself from postfjord_preview_post for channel-specific crops, so an agent can tell the three tools apart without opening any schema.

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?

Gives a concrete usage trigger: 'Use it after postfjord_upload_media to see when the file is ready', with expected latency for pictures vs videos. It also routes the channel-crop case to postfjord_preview_post. It stops short of saying when to use postfjord_list_media instead of this tool for browsing, so not a full 5.

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