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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral detail beyond that: record counts for list, returned fields for get, browse-level limits up to 5,000 entries, and the narrowing effect of the contains parameter. No contradictions with annotations exist.

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-organized into a compact bullet list with no wasted words. Each action gets a focused line, examples are embedded efficiently, and the browse-tree traversal example communicates a complex idea in a concise form.

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 tool with three actions and seven parameters, the description covers the main behaviors, parameter relationships, and return highlights well. It could be slightly more complete by explicitly noting pagination semantics for list versus browse, but the schema already documents start and count, so the description is largely sufficient.

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 100%, so the baseline is 3, but the description adds meaningful parameter semantics: it maps actions to their required parameters, explains path as labels chosen so far, and gives concrete examples such as name="1812 pension" and path=["South Carolina","Hunt"]. This goes beyond the schema's isolated property descriptions.

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 names a specific resource (Fold3 collections) and enumerates three concrete actions: list, get, and browse. Each action is tied to a clear verb and resource, and the examples make it easy to tell this tool apart from siblings like fold3_search or fold3_record.

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 clear context for each action, including which parameters each action needs and illustrative use cases. It does not explicitly name sibling tools or state when not to use this tool, but the action-specific guidance leaves little ambiguity.

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

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.

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

Annotations already declare read-only, idempotent, and non-destructive, so the bar is lower. The description adds behavioral detail beyond annotations: it lists allowed endpoint prefixes and the POST DocumentQuery action, and implies that raw requests bypass the filtering/projection of the other tools, which is important context for safe use.

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?

Two sentences with no filler. The core purpose is front-loaded, and the routing advice ('prefer other tools') follows logically. Every sentence earns its place.

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 raw-access fallback with open-world semantics and no output schema, the description covers the essential usage constraints (allowed paths, methods, documentation reference, and the caveat about raw results). An agent can safely decide when to call this tool and how to construct a request.

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 100% (all parameters described), so baseline is 3. The description adds meaning beyond the schema: it explains that POST is used for a DocumentQuery, ties the path to specific prefixes, and implies that body is only for POST, which complements the schema's brief descriptions.

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 ('request'), resource (Fold3 services), and allowed paths/methods. Clearly distinguishes from siblings by saying it provides 'data the other tools lack' and explicitly naming the alternative tools in the preference note.

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 says 'Prefer the other tools' and explains why (projected results, checked filters), indicating when NOT to use this tool. Also points to docs/endpoints.md for useful paths, giving an actionable guide for correct usage.

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

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

Annotations already flag the operation as read-only, idempotent, and non-destructive, and the description adds rich behavioral detail beyond that: FILE paging behavior, dropped '[Blank]' fields, per-page imageId exposure, account-level viewability, and MEMORIAL's linked Ancestry records. This gives an agent an accurate model of what the tool actually returns and how it behaves.

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 front-loaded with the core action and then uses a clean bullet structure to cover each type without redundancy. Every sentence and bullet earns its place; the length is justified by the tool's five distinct record types.

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?

With no output schema, the description carries the burden of explaining return behavior, and it does so thoroughly for every type. It also covers input alternatives, paging, and the boundary with fold3_download. An agent has enough information to select the correct parameters and interpret each record type's response.

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 every parameter at 100% coverage, but the description adds meaningful semantics beyond those descriptions: id+type can be replaced by url, type values map to different response shapes, SUB_IMAGE returns imageId and line, and MEMORIAL provides collectionId + recordId for ancestry_record. This materially helps an agent construct correct calls.

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 clear verb-resource pair, 'Read one Fold3 document,' and immediately distinguishes the supported variants (FILE, IMAGE, INDEX_RECORD, SUB_IMAGE, MEMORIAL). It is specific and differentiates from siblings like fold3_download by stating images themselves come from that tool.

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 clearly explains the input modes ('id + type' or 'url') and routes image retrieval to fold3_download with an explicit statement: 'Images themselves come from fold3_download.' It does not exhaustively enumerate when not to use other siblings such as fold3_search or fold3_session, but the intended usage context is strongly implied.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral detail: hit types and their structure, limits (50 per call, first 10000 hits), subscription requirements for viewing images, and the caveat that coverageYear is a generic filter that does not filter personal dates. This goes well beyond the annotations.

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 long but well-structured with bullet points for the two actions. Every sentence adds value: it covers scope, hit types, limits, subscription, and follow-up steps. It front-loads the core purpose and efficiently organizes the operational details without redundancy.

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 (20 parameters, two actions, no output schema), the description is remarkably complete. It explains the return format (hit types and fields), pagination limits, subscription nuance, and the relationship to fold3_record. An agent has everything needed to invoke it correctly and interpret results.

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 100% with detailed per-parameter descriptions, so the baseline is 3. The description adds meaning beyond that by explaining that search requires at least one criterion, that facets returns counts, that count has different meanings per action, and that only the first 10000 hits are reachable (affecting start/count). It also clarifies the relationship between name and keywords, which is useful for parameter selection.

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 states a specific verb ('Search') and resource (Fold3's military and other historical records), enumerates the record types, and distinguishes the two actions (search vs. facets). It clearly differentiates from sibling tools by describing its role as the search entry point and pointing to fold3_record for reading a specific hit.

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 each action (search for hits, facets to pick filters before paging), notes that searching requires no subscription, and instructs the agent to use fold3_record for reading hits. It also mentions consulting fold3_session for subscription status, giving clear context for selection among siblings.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds context: login uses the saved Ancestry session, has no browser or password interaction, and status reports signed-in status, account type, and premium access. This goes beyond the annotations by explaining the mechanism and prerequisites, though it doesn't detail failure modes or side effects of repeated logins.

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 two sentences, concise and front-loaded with the core purpose. It explains both actions and provides a critical usage note without redundancy. Minor inefficiency: the phrase 'The Fold3 sign-in' could be more precise, but overall it's well-structured and every sentence earns its place.

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 session-management tool with a single parameter, the description covers the essential return values for status, the login mechanism, and the prerequisite. It does not have an output schema, but it adequately describes what the agent can expect. The note about login being rarely called directly fills a practical gap. Some detail about error handling or idempotency confirmation is absent but not critical.

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 only lists the enum values 'status' and 'login' with a terse description. The description enriches these by defining exactly what status returns (signed-in status, account subscription level, premium access) and what login does (signs in via Ancestry session). Since schema coverage is 100% but the enum descriptions are minimal, the description adds meaningful semantic detail.

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 states that this tool manages the Fold3 session, covering 'status' and 'login' actions. It clearly differentiates from sibling tools like fold3_search and fold3_download by focusing on session state rather than data retrieval or downloads. While the opening phrase 'The Fold3 sign-in' is a bit noun-like, the subsequent explanation makes the purpose explicit.

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 says 'Downloads sign in by themselves when needed, so login is rarely called directly,' which tells the agent when not to call login. It also specifies that login requires a valid Ancestry session (via ancestry_session status), giving a clear precondition. This directly addresses when to use status versus login and when to avoid the tool altogether.

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