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

Adds substantial behavior beyond the annotations: 25 MB ceiling with the exact 'too_large' error shape, filename/mime fallback to 'upload' + application/octet-stream, and the important partial-failure semantics (linking fails with HTTP 500 but the file persists — do not re-upload) plus draft-first guidance. The gap: destructiveHint=true is never explained — nothing says whether a name clash overwrites, creates a duplicate, or fails.

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?

Well front-loaded: the core input-mode decision comes first, then routing, then linking, then metadata. Length is justified by 11 undocumented parameters, but it is an undifferentiated prose block and the explicit return-shape sentence duplicates the existing output schema.

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 mutation tool with destructiveHint, openWorldHint, 11 params at 0% schema coverage, and an output schema, the description supplies everything an agent needs: input-mode selection, size limits and error tokens, linking recipe and safe fallback, accessibility expectations, and return-value consumption guidance.

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 0%, so the description carries the entire burden — and it covers all 11 parameters: source_url/file_base64 semantics and mutual exclusion, filename/mime_type requirements per mode, ref (content-type UID, do not guess), ref_id (numeric id, NOT documentId), field example, full, alternative_text/caption, and workspace scoping. This is exactly what a 0%-coverage 11-param schema needs.

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 ("Datei in die Strapi-Medienbibliothek hochladen") and immediately scopes it to two mutually exclusive input modes. It also distinguishes itself from the neighboring siblings it could be confused with (strapi_generate_upload_link, strapi_list_media, strapi_update_media, strapi_update_entry).

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?

Explicit branch logic: source_url vs. file_base64 ("Genau eines angeben"), plus a hard routing rule to strapi_generate_upload_link for chat attachments and customer-local files. It also gives a preferred path for the risky ref/ref_id/field linking case (upload without ref, then strapi_update_entry) and when full=True beats a later strapi_list_media call.

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