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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context not available in annotations: the upload tools show nothing and require this call, create_upload_page self-renders and must not be followed by view_pdf, the job_id must originate from specific tools, and there are mandatory post-conditions (render download link, follow cta_instruction). This goes well beyond the annotation safety profile.

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 longer than average but well-structured with clear sections, bolded emphasis, and bullet points. Each paragraph serves a distinct purpose: core definition, usage triggers, upload caveat, job_id constraints, and post-conditions. While lengthy, the information density is high and layout improves scannability; a slight trim could make it a 5.

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?

Given the tool's complexity (interaction with upload flow, job_id provenance, post-conditions), the description covers all necessary context. It addresses common mistakes (forgetting to call after upload, inventing job_id), specifies the exact call sequence, and provides mandatory follow-up actions. The output schema exists, so return value details are not needed in the description.

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?

The schema already describes both parameters with 100% coverage, giving names and brief descriptions. The description adds critical semantics for job_id: it must come from upload_pdf, batch_upload_pdf, or check_upload_status; never invent or use a filename. This is valuable beyond the schema, though session_id receives no additional detail. With high schema coverage, baseline 3, and added job_id guidance, a 4 is appropriate.

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 'Display an already-uploaded PDF in an interactive viewer widget,' which uses a specific verb ('display') and resource ('already-uploaded PDF') and clearly differentiates from siblings like upload_pdf and create_upload_page. It explicitly notes the upload tools show nothing, reinforcing the unique purpose.

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 explicit when-to-use guidance: after delete_pdf_page, set_password, change_password, redact_pii, redact_by_text_range, and when the user asks to re-display. It also covers when NOT to call (after create_upload_page) and warns that after upload_pdf/batch_upload_pdf you MUST call view_pdf, giving clear conditional logic and alternatives.

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