export_social_media_kit

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

With no annotations, the description carries the full burden; it does disclose that files are written into output_dir and specifies the exact return shape ({exported: [{platform, file_path, width, height}], count}). It omits important behavior for a write tool: overwrite behavior for existing files, whether the full kit is atomic, and what happens with invalid platform names (the schema's array items are untyped, so bad input is plausible).

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-loaded with the purpose, then structured into platform sizes, parameters, and return value, all of which earn their place. The only mild redundancy is repeating platform names in both the size table and the parameters section, though the repetition serves different purposes.

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?

Because there is no output schema, the explicit Returns line is genuinely valuable, and the platform size table resolves the untyped array parameter. What keeps it at a 3 is the unresolved ambiguity around image_index and the absence of any statement about the source document state or file-overwrite semantics for a multi-file write operation.

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 0%, so the description must compensate, and it does: it documents all three parameters and, critically, supplies the valid platform identifiers that the schema leaves as an untyped array. The one weak spot is image_index, described only as 'Source image index (default 0)' without saying which collection or ordering the index refers to.

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 ('Export an image resized for multiple social media platforms') and enumerates the exact platform variants produced, which distinguishes it from the many other export tools in the sibling list. It stops short of naming which sibling to prefer for non-social exports, so the differentiation is implicit rather than explicit.

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?

Usage is inferable from the name and platform list, and the description does give one routing hint by parameter ('omit for all five'). However, it never says when to use this versus export_image, batch_export, export_web_optimized, or export_icon_sizes, and never states prerequisites such as needing an open image.

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