WordPress: Generate and upload image

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

The annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=true, so the write/non-idempotent profile is known. The description adds genuinely useful context beyond that: it resolves credentials from the caller's stored provider key and falls back to server env vars, and it discloses the optional post-attachment and featured-image side effects. However, it says nothing about cost, rate limits, failure behavior when the provider errors mid-way (image generated but upload failed), or what other mutations occur during optimization/conversion.

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?

Three sentences, front-loaded with the unified action and provider list, then the optional side effects, then credential resolution. The bracketed '[UNIFIED]' tag is slightly noisy but each sentence carries distinct information and nothing is repeated from the annotations.

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 an 18-parameter tool with no output schema and zero schema descriptions, the definition is thin. An agent cannot determine what the return value contains (media ID, URL, attachment status), what convert_to accepts, what input_images_b64 does, or how to recover when generation succeeds but upload fails. The credential fallback is the only behavior fully covered.

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% across 18 parameters, so the description must carry the burden and it does not. It only touches provider, prompt implicitly, attach_to_post and set_featured; parameters like input_images_b64 (which appears to enable image-to-image or editing), convert_to, skip_optimize, generate_og_variant, negative_prompt, quality, size, filename, alt_text and connection_id are entirely unexplained anywhere.

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 states a specific compound action: generate an image via a named AI provider (DALL-E, Stability, Replicate Flux) and upload it to the WordPress media library in one call. That distinguishes it from pure-upload siblings such as wordpress_upload_media_from_url and wordpress_upload_media_from_base64, although the differentiation is by implication rather than an explicit comparison. The scope is clear enough that an agent knows exactly which capability it is selecting.

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?

It implies usage ('in one call', 'Optionally attach to a post or set as featured image'), so an agent can infer this is the shortcut when generation and upload should be fused. But it never says when to prefer the separate generate/upload path, when to use the base64 or URL upload siblings, or that this tool incurs provider API cost. No exclusions or prerequisites are stated.

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