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

Annotations already flag openWorldHint and non-read-only behavior, and the description goes well beyond them: it discloses that GoldSeam server-side fetches image_url, that the view may refuse other sites' pictures, a 1 MB size ceiling, the split-screen layout effect, and the important caveat that 'queued is not evidence the person saw it.' That is exactly the kind of behavioral context annotations cannot 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?

Purpose is front-loaded in the first clause, but the prose is dense and runs long sentences with stacked clauses (fetch behavior, layout, usage triggers, and the queued caveat all in one block). Everything is relevant, yet several clauses could be shortened or split for faster scanning.

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 six parameters, one required boolean, and an output schema present, the description covers the remaining gaps: side effects on the coach view, image fetching constraints, lifecycle (open/close), and the meaning of the queued response. An agent has everything needed to call it correctly and interpret the result.

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 100%, so the baseline is 3; the description still adds meaning the schema does not: image_url must be an https address that the server fetches, size-capped at 1 MB, show=false is the close path, and coach_id comes from open_coach. Title and caption get no additional treatment, so it is not exhaustive.

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 names a specific verb pair (show/close) and resource (the whiteboard beside the open coach) and enumerates its contents (title, answer text, picture). It is clearly distinguishable from coach_say and coach_listen, though it never names those siblings explicitly to draw the contrast.

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 gives concrete triggers: use when the person asks to see something (a campus, a chart, an answer written out) or asks for the whiteboard, and pair it with an answer whose key points or picture help them follow. It also gives the closing condition ('close it when they are done') and points to open_coach for the coach_id.

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