ops_download_pdf

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

Annotations only declare readOnly=false/idempotent/openWorld; the description adds substantive traits: per-page billing against a 4GB weekly quota, output location (TW_PATENT_MCP_DOWNLOAD_DIR, default ~/.tw-patent-mcp/downloads), automatic multi-page merging, and adaptive throttling based on OPS rate-limit signals. This is exactly the side-effect and cost context an agent needs before a quota-consuming call.

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?

A single dense paragraph where every sentence carries information: purpose, input format, cost warning, save location, merge behavior, throttling. Slightly run-on and could be broken into bullets, but there is no filler.

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 values need not be explained, and the description covers the remaining gaps an agent faces: where files land, how merging works, and the quota cost of multi-page downloads. Nothing needed to call it correctly is missing.

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 0%, so the description must compensate, and it documents link (source and example format), pages (syntax plus the 'all' variant), and max_pages (required when pages='all'). Only 'merge' is left unexplained, though '多頁自動合併' implies its default behavior.

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 specific verb and resource ('下載 EPO OPS 影像 PDF') and explicitly ties itself to the sibling ops_images as the source of the link. An agent can distinguish it from ops_images (metadata/pages) 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?

It states the precondition (link must come from ops_images), the accepted formats ('1-5' or 'all' requiring max_pages), and a concrete recommended workflow: check page count with ops_images first, then decide the range. It also warns that each page is a separate call counted against the weekly 4GB quota, which steers scope decisions.

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