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

Annotations declare this is a non-read, non-destructive, non-idempotent write. The description reinforces that by saying the result is 'saved as a new image' and returns a fresh media_id/url, implying each call produces a new artifact rather than updating in place. It adds platform-specific behavior (which networks honor an image cover vs a frame time, long-video-only on YouTube) that annotations cannot convey, though it omits auth or rate-limit notes.

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?

Front-loads what the tool produces, then the workflow links, then platform rules. Information-dense with almost no waste, though the long trailing platform enumeration is bulky and could be trimmed for agents that only need to invoke the tool.

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?

An output schema exists so return values need little explanation (they are still named), and the description covers inputs, cross-tool workflow, and per-platform handling. For a non-idempotent creator tool with four parameters, nothing an agent needs to call it correctly is missing.

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 100%, so the baseline is 3; the description rises above it by linking media_id to specific sources (suggest_cover frame / brand image / video) and clarifying that offset_ms is the video frame time. This cross-tool context is not derivable from the schema alone.

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+resource with full scope: a title drawn over a picture, saved as a new image. It clearly separates this from suggest_cover (which supplies frames) and from add_media, so the agent can pick it without opening the 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?

Explains exactly where the source picture comes from (a suggest_cover frame, any brand image, or a video with offset_ms) and how the result plugs into update_post as cover_media_id with thumb_offset_ms=null. It also enumerates per-platform applicability, which is real when-to-use context. It stops short of an explicit 'use this instead of suggest_cover when...' exclusion, keeping it at 4 rather than 5.

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