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

The description discloses validation behavior beyond the annotations: file size max 50 MB and merged page count max 30 pages including the letter and other attachments. This informs the agent about important failure conditions that are not visible in the schema or annotations. It doesn't mention side effects or what happens on validation failure, but the added constraints are meaningful.

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 description is bilingual and repetitive, but each language contains a clear purpose sentence followed by a validation sentence. There is no filler, and the action is front-loaded. The duplication makes it longer than strictly necessary, but it remains tightly structured.

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 covers purpose and validation limits, but for a 6-parameter mutation tool with no output schema it leaves gaps: it doesn't state that at least one of pdfUrl/pdfBase64 is required for a successful call, nor explain the role of position, title, or reasoning. It is adequate for basic understanding but incomplete for reliable invocation.

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 only 33% (only pdfUrl and pdfBase64 have descriptions). The tool description adds no parameter-level guidance: it doesn't explain letterId, title, position, or reasoning, and doesn't clarify that pdfUrl and pdfBase64 are mutually exclusive alternatives. With low schema coverage, the description fails to compensate.

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 states a specific verb and resource: 'Lädt ein PDF als Anhang zu einem Partner-Brief hoch' / 'Uploads a PDF as an attachment to a partner letter.' The PDF qualifier clearly distinguishes this tool from the sibling attachment_upload_image, and the partner-letter context separates it from other upload tools like letterhead_upload or signature_upload.

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?

The description provides clear context for when to use the tool: when a PDF needs to be attached to a partner letter. It does not explicitly name alternatives or exclusions, such as pointing to attachment_upload_image for images, but the purpose statement leaves little ambiguity about the intended use case.

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