Placeholder image

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

Annotations already declare readOnlyHint, idempotentHint and closed-world, so the safety profile is covered. The description adds genuinely useful behaviour beyond that: default text is 'W × H', '\n' breaks lines, font size auto-fits unless fixed, and text renders in Inter when installed else a system sans-serif. It omits the file-writing side effect and where the result lands, which is the main residual gap.

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?

A single dense paragraph, front-loaded with the core action, then capabilities, then caveats. Most clauses earn their place; the trailing link to the project website is marginally useful context rather than noise, though it slightly dilutes the operational content.

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 12-parameter, all-optional generator with no output schema, the description covers what is produced (image file, optionally data URI/base64/<img>), the format and size envelope, and rendering defaults. The one thing an agent still can't infer is the concrete return shape/path when only a file is written, which would matter for chaining calls.

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 100%, so every one of the 12 parameters is already documented in the schema, making 3 the baseline. The description echoes a subset (default text, newline syntax, formats, auto-fit font, data URI for small images) but adds no syntax or constraint detail the schema doesn't already carry.

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?

Opens with a specific verb+resource — 'Make a placeholder image of any size' — and enumerates the salient capabilities (solid background, centred text, auto-fit font, four output formats, size presets). An agent can immediately distinguish this from neighbours like image_resize, image_convert, or image_ascii_banner, which all transform existing images rather than synthesise one.

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 concrete usage context — 'Size presets for web, social media, IAB ads and devices' and 'for inlining' for the data URI option — which tells the agent when this tool fits. It stops short of naming alternatives or stating when not to use it (e.g. vs image_resize for editing an existing asset), so it falls just below the explicit-alternatives bar.

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