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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the write/open-world profile is known. The description adds useful behavior (it persists into a personal library and returns a /media URL) and the one-source rule, but says nothing about size limits, allowed formats for data, overwrite behavior, or what happens if both sources are passed. With annotations carrying the safety profile, this is a moderate contribution rather than a rich one.

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 purpose, return value and source rules are front-loaded in a dense telegram style with no filler sentences. The vocabulary style guidance is arguably task advice beyond the tool contract, but it is short and directly relevant to correct invocation.

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 3-parameter write tool with no output schema, the description covers the essentials: what is stored, what is returned (the /media URL), the two mutually exclusive source modes, and constraints on each. Missing details are secondary (error behavior, limits on data payload, handling of the optional name), so an agent can call it correctly as written.

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 baseline is 3, but the description adds meaning the schema does not express: the mutual exclusivity of url and data (a real risk since required-parameter count is 0), the rule that data must be an image generated in this session, and content guidance for vocabulary images (recognizable object, light background, no text or watermark). That goes beyond restating the schema descriptions.

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?

"Legt ein Bild in der Bibliothek der Lehrkraft ab und gibt die url (/media/…) zurück" is a specific verb + resource + return value, and it names the concrete consumers (Vokabelkarte, Board). An agent can distinguish this from siblings such as list_images or share_file without opening the schema.

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?

"Genau eine Quelle" plus the per-parameter explanation tells the agent that url and data are mutually exclusive alternatives and which is appropriate (a generated-in-session image goes to data, an external link to url). The negative constraints ("keine Suchseite, kein Artikel", "Erfinde nie einen /media-Pfad") steer away from the main failure mode, but no sibling tool is named as an alternative for other storage needs.

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