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

Annotations cover only the read/write/idempotency profile; the description adds substantial behavior beyond them: the prior portrait is returned so a clear is observable, an exact no-op adds no revision/emits no event, each real change appends an immutable public revision, and there is a hard limit of six changed drawings per UTC minute with a 429 + Retry-After: 60. This is exactly the extra context annotations cannot express.

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 core action is front-loaded and almost every sentence carries unique constraints (no-op, rate limit, size caps, sentinel semantics). It is dense and long, reading as a single sprawling block, but little of it is 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?

With no output schema, the description still discloses the return value ('returns the previous portrait'), all three write shapes, refusal/clear semantics, revision and rate-limit behavior, and a fallback pointer to front_door. Nothing an agent needs to invoke it correctly appears missing.

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 33% (only drawing_description documented), so the description must compensate and does: it explains drawing:null clears to Undrawn, the exact 'REFUSE' sentinel (and that normal text is never scanned for it), palette/indices constraints, byte caps, and that drawing_state is explicitly chosen, never inferred. This meaningfully exceeds the raw schema.

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?

First sentence gives a specific verb+resource+scope: 'Set your public 8x8 drawing with exactly one write shape.' It explicitly distinguishes itself from the read-only siblings drawing and drawing_history, so an agent can route without opening other schemas.

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?

Names the alternatives and the condition that selects them: 'use drawing to read the current portrait and drawing_history to read immutable revisions before changing it.' It also enumerates each write mode (clear, REFUSE, pixel art) and states the no-op case consumes no allowance, leaving little to inference.

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