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

Beyond the annotations, the description discloses important runtime behavior: attachments without 'tag and nummer go to the session, limits are 50 attachments per session and 50 MB per file, storage-plan errors are reported in plain text, and deletion is not supported via this tool. This is substantial behavioral context beyond the structured annotations.

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?

Though longer than average, the description is well structured and front-loaded with the core action, then rationale, then placement, duplicate, limit, and error information. Every sentence adds operational value rather than restating the 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?

The description is complete for a mutation tool with no output schema: it covers what the tool does, when to use it, placement rules, limits, failure behavior, and how attachments are removed. An agent can correctly invoke it with confidence.

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 a baseline of 3 applies. The description adds extra value by explicitly explaining the combined effect of 'tag' and 'nummer' on placement at the session level, and by grounding the duplicate-check behavior in 'session_lesen'. That pushes it above the baseline.

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 opens with a precise verb and resource: 'Hängt eine Datei an ein Modul oder an die ganze Session' and gives concrete examples. It clearly distinguishes this tool from the sibling module/session management tools because it uniquely handles file attachments.

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 explains the intended use case explicitly: large files referenced by an imported guide should be attached rather than put in 'material'. It also gives when-not guidance: check 'session_lesen' under 'anhaenge' before sending duplicates, and notes removal is only possible in the app.

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