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

Annotations only declare non-readOnly, non-idempotent, non-destructive, openWorld. The description adds material context beyond them: it persists the file to the user's account, performs an A4/free-margin print check, sends nothing, and requires the user's account (auth). It does not address repeat-upload/duplicate behavior, which is the one trait left implicit for a non-idempotent write.

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?

Front-loads the trigger, then the effects, then the failure path and alternative, then the safety/auth notes. Every sentence carries a distinct, actionable fact with no repetition.

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-param, no-output-schema tool, it covers purpose, effects, return value (document_id), auth, and alternatives. The remaining gap is that it does not clarify the exactly-one-of pdf_url/pdf_base64 requirement implied by zero required parameters.

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 only 33% (just pdf_base64 documented), so the description does carry weight by naming the two input forms (URL vs base64). However it never mentions file_name, never states that exactly one of pdf_url/pdf_base64 is needed despite required parameters being empty, and adds no format or size detail beyond what the schema already says for base64.

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'), plus the accepted input forms (public https URL or base64) and the end state (stored in the account, print-checked, returns document_id). It is clearly distinguishable from create_upload_link and fix_document_margins, which it names.

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?

Explicitly gives the trigger ('when the user already has a PDF'), the alternative for the on-device case ('use create_upload_link instead'), and the remediation path if the print check fails ('call fix_document_margins or ask the user for a corrected file'). This is a complete routing decision.

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