Download Fold3 images

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

Annotations already indicate idempotentHint=true and destructiveHint=false, and the description adds valuable behavioral context: it stitches from viewer's tiles, the site's own download is capped at 1600 px, pages already on disk are kept, and it signs in through Ancestry by itself when needed. It also discloses that full-resolution pages take several seconds and that at most 40 pages per call. This goes beyond the annotations and helps the agent anticipate side effects and performance. A small gap: it doesn't explicitly state what happens if a page fails mid-download, but overall strong.

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 well-structured with a clear intro, bullet-like action breakdown, and a final note on access. It is somewhat long but every sentence carries useful information. The front-loading of the main purpose and the action list helps an agent quickly parse it. Slight verbosity in the access note could be trimmed, but it's justified for transparency.

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 has 8 parameters, no output schema, and moderate complexity (two actions, continuation, resolution scaling), the description covers the essential context: what each action does, required parameters, defaults, limits, and access behavior. It doesn't describe the exact structure of manifest.json beyond listing ids, sizes, SHA-256, but that is likely sufficient for an agent to proceed. The lack of an output schema is partially compensated by the description's detail on return behavior (inline vs file writing).

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 100%, so the schema already documents all parameters. The description adds meaning by explaining the relationship between parameters (e.g., image needs imageId, file needs fileId and outDir, maxSide default behavior differs for inline vs outPath, start for continuation). This is more than the schema alone provides, though the schema already covers the basics. A 4 is appropriate because the description enriches parameter semantics without being redundant.

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 clearly states the tool fetches Fold3 page images at up to full resolution, and distinguishes the two actions (image vs file) with their required parameters. It also differentiates from siblings by mentioning it is the download tool, while siblings like fold3_search, fold3_record, fold3_collection, fold3_session, and fold3_raw_request serve other purposes.

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 explicitly explains when to use the image action (one page, needs imageId) and when to use the file action (multi-page file, needs fileId and outDir). It also notes the 40-page limit and the start parameter for continuation, and mentions that it works for collections the account may view, with subscription requirements disclosed. This is strong guidance for an agent to select the correct action and parameters.

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