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

Annotations only declare write semantics (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds crucial non-obvious behavior: the call returns JSON containing a curl_command that is already shell-escaped and must be executed verbatim, and the uploader identity is derived from the OAuth user rather than a submitted field. That is high-value disclosure the annotations cannot convey.

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 critical fact (no file bytes through this tool) is front-loaded in the first clause, and the remaining sentences each carry a distinct constraint. It is somewhat dense with stacked prohibitions, but nothing is padding.

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?

An output schema exists, so return-value explanation is not required, and the description still notes the curl_command payload. For a write tool with a three-branch anyOf schema, the description coherently steers the agent to the correct branch and covers the required invocation step, though it leaves the application_json variant's contract for the agent to infer.

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?

Reported schema description coverage is 0% for the top-level param, so the description must compensate, and it does: it marks filename as required (local PDF path, no control characters), name as optional and only when it should differ from the basename, description as optional, and explicitly forbids sending uploaded_by. It does not describe the base64/pdf variant fields, which the schema still contains.

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?

States a specific verb and resource ('Upload a PDF attachment') and immediately resolves the confusing tool name by clarifying that file bytes are NOT sent through this tool. It implicitly separates itself from the sibling upload-attachment_application_json by forbidding base64 encoding, so an agent can distinguish the two without opening either 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?

Gives clear situational context (MCP client sends metadata only; the returned curl_command performs the actual byte upload) plus explicit exclusions ('Do not base64-encode', 'do not use generate-api-key for uploads'). It does not name the application_json sibling as the alternative for API-key clients, so the when-to-use-the-other-variant guidance is left implicit.

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