Make the final file for a platform

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

With no annotations, the description carries the load well: it discloses cropping behavior ('cropped to fill'), the quality strategy (lowest JPEG quality that passes SSIM), metadata stripping, enforcement of per-platform size limits, and a post-hoc empty-band validation. Gaps remain around overwrite behavior when the target exists and what the tool actually returns, but the mutation semantics are mostly spelled out.

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?

Purpose and pipeline are front-loaded in the first clause, before the reference-style platform table, which is the right ordering. The platform enumeration makes the single sentence very long and comma-heavy, but each entry carries distinct resolution/intent/size information rather than filler.

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 four-parameter tool with no annotations and no output schema, the description covers the processing contract, per-platform target semantics, and size ceilings — enough for an agent to call it correctly on the first try. Only overwrite semantics and return-value expectations are unaddressed, which are minor against the overall coverage.

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 only 25% (only output_path is documented), so the description must compensate — and it does heavily for the most important parameter, giving every platform enum value a resolution, use case, and in some cases a byte limit (2 MB YouTube, 1 MB GitHub). input_path and overwrite are not explained anywhere, and overwrite's default-false implication is left implicit, so it is not fully compensating.

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 concrete verb and outcome: turn a finished image into the exact file a platform expects, and enumerates the processing steps (crop-to-fill, JPEG/SSIM, metadata strip, size cap, empty-band check). The platform list with dimensions and intent makes the scope unmistakable and lets an agent tell it apart from neighbors like social_sizes or media_optimize even without naming them.

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?

'One step from a finished image to the file a platform wants' establishes when to reach for it, and several enum entries carry real disambiguation guidance (linkedin-link is a 'link preview card, not a feed post'; instagram-story needs text kept out of the top 14%/bottom 20%). It stops short of naming sibling alternatives (compose, media_optimize, social_sizes) or stating preconditions such as source image requirements.

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