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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses that the shot becomes public under the user's name, that publish_at schedules it, that confirmation is on by default and can be disabled, and that a Cotlet API key with app access is required. This is rich post-invocation and auth context that structured fields do not carry.

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?

The first two sentences substantially overlap ('Publish a new shot from an image, with title, description and tags' vs 'Publishes a new shot on your profile from an image URL, with a title, an optional description and tags'). The later sentences on scheduling, confirmation, and auth do earn their place, but the redundancy costs the score.

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 creation tool with no output schema, the description covers visibility (public, under your name), scheduling, confirmation policy, and credential requirements. It does not mention the return value or any publish limits, but the essential context for calling it correctly is present.

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 the schema already documents all five parameters including their formats. The description only restates title/description/tags and hints that publish_at schedules the shot, adding nothing the schema lacks — the baseline 3 for full coverage applies.

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 verb and resource — 'Publish a new shot from an image' — and names the key inputs (image, title, description, tags). The word 'new' implicitly distinguishes it from the sibling dribbble_update_shot, but no sibling is named explicitly.

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 offers operational context ('Set publish_at to schedule it', 'confirm with the user before each call'), which implies usage but never states when to choose this over dribbble_update_shot or another sibling. No explicit when/when-not framing.

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