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

The annotations already mark this as read-only and open-world, but the description adds substantial behavioral detail: token_accepted asks FamilySearch, authenticated only means a token is set, tokens last about an hour, no client ID is shipped, and production access requires a registered app.

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 purpose, then adds only essential caveats about token lifetime, the distinction between authenticated and token_accepted, and production requirements. Every sentence is useful and no space is wasted.

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?

Even without an output schema, the description explains the key returned concept token_accepted and what authenticated means. It also covers setup prerequisites and the external call scope, so an agent has enough information to invoke and interpret this tool correctly.

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 tool has zero parameters, so parameter semantics are not applicable. The baseline for a parameterless tool is 4, and the description appropriately does not invent parameter information.

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 and resource: report credential configuration status and what is missing. It also explains the token_accepted behavior, making it clearly distinct from the data-retrieval sibling tools.

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 makes the context of use clear: checking configured credentials and optionally testing a token. It does not explicitly name when to use this over alternatives, but no sibling tool overlaps with auth status, so the implied usage is sufficient.

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 declare readOnlyHint and openWorldHint, so safety is covered. The description adds real surface beyond that: an error constraint ('FamilySearch refuses a waypoint without its collection'), an auth disclosure ('Works without a token'), and a response behavior ('A collection with nothing to browse says so') — all useful for an open-world tool.

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?

Purpose is front-loaded and no sentence is pure filler. The prose is slightly fractured and rhetorical ('The way to reach a page the index never covered'), but each statement carries usable information.

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?

There is no output schema, yet the description covers the traversal workflow, the token requirement, the collection/waypoint coupling, and the empty-collection case. Enough for an agent to invoke it correctly, though the exact return shape of a waypoint listing is left implicit.

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 per-field baseline is 3. The description adds cross-parameter meaning the schema states only per field: collection_id is the entry point, and descent requires passing a child's waypoint_id together with the same collection_id.

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 (browse) and resource (a collection's waypoint structure: places, volumes, images), and the hierarchy it navigates. It distinguishes itself from siblings by naming get_image_links as the route for image arks, so an agent can tell them apart 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?

Gives a clear when-to-use ('the way to reach a page the index never covered') and prescribes the traversal order (collection, then county/volume/date range, then images). It names the alternative for image arks (get_image_links), though it never explicitly states when to prefer get_collection or search_collections instead.

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 only give readOnlyHint and openWorldHint, yet the description goes far beyond them: it discloses that nothing is changed, that 'packets' of proposed changes are drafted for manual execution, that living persons are refused, that an access token is required, and that the tree is community-edited with common same-name conflations. This is exactly the extra behavioral context the annotations cannot carry.

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?

Purpose and the no-mutation guarantee are front-loaded, but the prose is dense with layered admonitions ('A difference is not an error', 'weigh it, never follow it', 'This is a hint where to look, not evidence') that overlap somewhat. Most sentences earn their place for a high-risk genealogy workflow, but trimming is possible.

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 does the work of explaining the return shape (agree/lacks/differs plus drafted packets) and the manual follow-up. Combined with the rich 100%-covered input schema and readOnly annotations, an agent has what it needs, though error or token-failure behavior is unstated.

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 every parameter, including confidence grading and source-URL matching, is already documented in the schema. The description reiterates the concept (confidence gates proposals, sources match by URL) but adds no syntax or value detail beyond it, so the baseline of 3 applies.

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 first sentence names a specific verb and resource: compare the caller's own record of one deceased person against their FamilySearch profile. It is clearly distinguished in kind from the retrieval siblings (get_person, get_ancestry), though no sibling is named explicitly, which keeps it just short of a 5.

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 sets context and preconditions well: confirm the profile is your person first, the tool refuses anyone possibly living, and the output is a hint to follow to a record rather than evidence. It does not name an alternative tool for the retrieval case, so it stops short of explicit when/when-not routing.

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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), it discloses the token-scoped fetch constraint (FamilySearch URLs only), the reason for disk output (multi-megabyte scans), and a copyright/redistribution caveat. No contradiction with the non-destructive, non-idempotent hints.

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-loaded with the core action in sentence one, then layered with rationale and caveats in short paragraphs. Slightly prose-heavy ('This is the step that turns a citation into evidence'), but every paragraph carries information an agent needs.

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?

There is no output schema, and the description fully covers the return behavior (file written to disk, not inlined), the auth scope, the no-overwrite rule, and the copyright caveat. Nothing an agent needs to invoke this 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 coverage is 100% and the parameter descriptions are already rich, so the baseline is 3. The description adds meaning to image_url by restricting it to FamilySearch URLs (the request carries the access token), a constraint the schema does not state.

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 opening sentence states a specific verb, resource, and outcome: 'Download a document image to a local file so it can be read.' This cleanly separates it from the URL-returning siblings (get_image_links, get_film_image), which the schema explicitly says feed this 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 gives clear context for when this is the right step ('turns a citation into evidence') and why the file is written to disk rather than returned inline. It does not explicitly name the upstream alternatives or state when not to use it, but the workflow position is easy to infer.

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 cover read-only/open-world, but the description adds substantial context: an access token is required, coverage is partial ('no result proves nothing'), the text is unreliable OCR of handwriting that must be verified against the image, and hits include a citation path. This is exactly the extra behavioral guidance the annotations cannot supply.

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?

Short paragraphs, front-loaded with the core action, then the caveat and the follow-up instruction. Every sentence carries information an agent needs (scope, edge cases, citation guidance, auth) with 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?

There is no output schema, yet the description describes what a hit contains ('one page image, with the passages that matched') and its citation path, plus the auth prerequisite and the coverage limitation. Nothing an agent needs to call and interpret this 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 100%, so the schema already documents all 8 parameters including search syntax, paging, filters and facets. The description adds no parameter-level syntax or format detail, so baseline 3 applies.

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?

Specific verb+resource: 'Search the machine-read text of page images: deeds, wills, probate, court files.' It clarifies the scope is full-text over page images rather than indexed records, which distinguishes it from siblings like search_records and get_records_on_image.

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?

Explains the distinctive use case (finding witnesses, heirs and neighbours 'no index names') and names the follow-up tool explicitly: 'open the image with get_image_links, read it yourself, and cite the image, never the text.' It doesn't state explicit exclusions for when NOT to use it versus search_records, so it falls just short of a 5.

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 cover readOnlyHint and openWorldHint, but the description adds substantial context beyond them: it discloses the access-token requirement, warns that lines beyond ~5 generations are frequently copied rather than researched, and flags that the shared tree is community-edited with common same-named conflations. These are material behavioral traits an agent cannot get from structured fields.

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 core action, then uses each following paragraph for a distinct purpose: output interpretation, sourcing caveats, and data-quality warnings. It is on the longer side and the sourcing-warning sentences could be tightened, but every sentence carries information rather than 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?

With no output schema, the description correctly compensates by explaining that the flat list is an Ahnentafel-ordered pedigree where a gap shows as a missing number, and it states the access-token prerequisite. Nothing essential for calling or interpreting the result appears to be 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 100%, so both person_id and generations are already documented in the schema, including the generation numbering (person=1, parents=2, grandparents=3). The description's Ahnentafel explanation restates and elaborates the same numbering, adding little param-level meaning beyond what the schema provides, so the baseline 3 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?

States a specific verb and resource with unambiguous direction: 'Walk a tree person's pedigree back through the generations.' The direction 'back' cleanly separates it from the descendant-oriented sibling get_descendancy, and the Ahnentafel explanation pins the exact scope without the agent needing the 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 gives strong context for how to treat the result — 'a hint where to look, not evidence: follow it to a record and cite that' — which frames appropriate use. However, it never explicitly names alternatives such as get_descendancy (downward) or get_person_relatives (immediate family), so the routing decision is left to inference from the wording rather than spelled out.

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 only supply readOnlyHint and openWorldHint, and the description adds genuinely new behavior: an access token is required, each returned item costs a request for its image count, items report viewability for this account, some films are restricted or never digitised, and DGS numbers differ from microfilm numbers. This is meaningful context 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?

Front-loaded with the core definition and generally tight, with each sentence carrying substance (cost, auth, DGS distinction, citation caveat). Some phrasing is elliptical ('An entry describes holdings, not a record: cite the image you read'), which slightly taxes readability, and the multi-paragraph layout is longer than strictly needed.

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 and five optional params, the description compensates well: it explains what is returned (image counts, viewability), the access-token requirement, per-item request cost, restriction status, and points to get_film_image for opening pages. An agent has everything needed to call it correctly.

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; the description nonetheless adds semantics the schema lacks, notably that film_number returns only that film's item and names the volume, and that contains should be used for very large item lists. It does not describe the numeric matching/span rules beyond what the schema already states.

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?

Opens with a specific verb+resource ('Read a FamilySearch Catalog entry') and enumerates what an entry holds (title, authors, places, notes, films). It also implicitly separates itself from siblings by stating an entry 'describes holdings, not a record', so an agent can distinguish it from get_record/get_film_image without opening schemas.

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?

Gives concrete selection conditions: use 'contains' when an item list runs to thousands, and use film_number when 'given only a film number (as an index citation gives it)'. It also steers away from treating the entry as a record. It does not explicitly name alternative tools for adjacent tasks, so it stops short of a full when/when-not/alternatives treatment.

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 and openWorldHint, so the safety profile is covered. The description adds real behavioral value: it explicitly notes 'Works without a token' (auth requirement), which is not in the annotations, plus the interpretive heuristic that a low image-to-record ratio means largely unpublished film.

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 core purpose, then progressively adds the pre-check tip and the count-interpretation nuance. Slightly stylized but every sentence carries usable information; 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?

With no output schema, the description takes on the burden of describing returns and does reasonably well, explaining that counts cover records, people and images and how to interpret them. It stops short of describing response shape or field names, but nothing critical for invocation 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 coverage is 100% and the schema already documents collection_id with an example and a pointer to search_collections. The description adds no parameter-level syntax or format detail, so the baseline 3 applies.

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: 'Read one record collection', and adds scope ('what it covers, and how much of it there is'). It implicitly contrasts with the plural search_collections sibling by saying 'one', but never names that sibling, so it falls short of a 5.

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?

Gives a concrete usage heuristic: read it before trusting a nil result. That is clear context for when to reach for it, though it names no alternative tool or exclusion condition, so it stops at 4.

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 cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description still adds real behavioral context: the codes are per-collection and it 'Works without a token', which tells the agent this call is safe pre-auth. It does not describe the return shape in detail, but that is a minor gap given 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?

Front-loads the purpose, then justifies it with concrete code examples and a when-to-use rule. The code examples (PR_FTHR_NAME, EVENT_PLACE) earn their place by making the concept tangible, though the three-line structure is slightly looser than a single tight sentence.

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 single-param, no-output-schema tool, the description covers the essential gap: what the tool returns conceptually (a per-collection code-to-label dictionary) and when it is needed. Nothing critical for correct invocation 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 100% and the single collection_id param is already documented with an example ('1417683') and a pointer to search_collections. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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 ('Decode the field codes a collection's indexed records use') and the value proposition is concrete: turning codes like PR_FTHR_NAME into 'Father's Name'. An agent can distinguish this from siblings such as get_collection or search_collections without opening the 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?

Gives clear usage context: 'Read it before interpreting a record from a collection you have not worked with.' This is an actionable when-to-use rule. It stops short of naming the alternative sequence explicitly (e.g. get_collection vs this), so it is not a full when/when-not routing statement.

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?

Adds substantial behavior beyond the readOnly/openWorld annotations: living descendants are withheld and returned as restricted, the tree is community-edited with common same-name conflations, results are a hint rather than evidence, and an access token is required. This is exactly the context annotations cannot carry.

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 purpose and proceeds in short, purposeful blocks, each earning its place. Slightly longer than strictly necessary but 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?

With no output schema, the description carries the return-value caveats (restricted living descendants) and the read caveat (hint, not evidence), plus the auth requirement. Nothing an agent needs before calling 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 100%, so person_id and generations are already documented in the schema. The description adds no parameter-level detail (no format, no syntax), so the baseline 3 applies.

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 ('walk a tree person's descendants forward') with the traversal direction made explicit, which cleanly distinguishes it from the sibling get_ancestry. An agent can tell what it does without opening the 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?

Gives a concrete use case for when this is valuable ('when a person's own record cannot be found, a descendant's obituary, probate or pension file often names him'), which is genuinely actionable. It stops short of naming alternatives explicitly or stating when not to use it.

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 cover read-only/open-world safety, but the description adds real behavioral context beyond them: it validates via the thumbnail first so a bad film/image number yields a clear error rather than a broken URL, and it discloses that the thumbnail requires no token while the full page does. That auth distinction is valuable for a tool whose result depends on credentials.

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-loaded with the core purpose, then the citation rationale and the thumbnail/token behavior. Every sentence carries information, though the opening ark-contrast and the source-pointer sentences could be tightened; nothing is 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?

With no output schema, the description still explains the validation path and the token requirement for the full image, which is the key operational nuance. Combined with 100% schema coverage on both required params and read-only annotations, an agent has what it needs; only the return shape of the thumbnail-vs-page result is left implicit.

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% and already documents both parameters including the leading-zero requirement and 1-based image numbering. The description reinforces the citation-sourced semantics of the two fields but adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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 ('reach a page image by film and image number instead of by ark') and immediately contrasts the addressing mode with the ark-based alternative. The sibling references (get_record_image, get_catalog_entry) let an agent distinguish it from other image tools without opening the 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?

Clearly says when to use it: when a citation names a film (DGS) and image rather than an ark, and names where those numbers come from (get_record_image, get_catalog_entry). It does not mention when NOT to use it or point to sibling alternatives such as get_image_links/download_image, so it stops short of a full when/when-not statement.

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?

With no output schema, the description carries the return-shape burden and does so concretely: storage node, deep-zoom descriptor, thumbnails at several sizes, `dist` for full resolution, plus neighbouring pages. It also discloses an auth-dependent behavior ('With a token it gives the film (image group) and image number'), which annotations do not cover.

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?

Purpose is front-loaded in the first sentence and the middle paragraph explains why neighbouring pages matter. The 'pension file or passenger manifest' example is illustrative but slightly atmospheric; the content still earns its place, so this is efficient rather than padded.

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 one-parameter read with no output schema, the description covers what comes back, the extra neighbouring-page payload, and the token-conditional citation data. Nothing an agent needs in order to call it and interpret the result 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 100% and the schema already documents image_ark in full, including its format and provenance. The description repeats the get_record_image provenance hint but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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 ('Resolve a document image to its actual, fetchable URLs') and explicitly positions itself against a sibling: a record read does not carry image links, this one does. The agent can distinguish this from get_record and get_record_image without opening a 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?

Explains the workflow context — take the ark from get_record_image's 'sources' entry where resource_type is DigitalArtifact — and rules out get_record as a source of image links. It stops short of stating when to prefer download_image or get_film_image among the many image-related siblings, but the entry condition is clear.

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 cover only readOnly/openWorld, and the description adds substantial behavior the schema cannot: an access token is required, record matches are restricted in production to certified apps and return a refusal otherwise, and results are system-scored guesses within a community-edited tree.

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-loaded with the core purpose and organized into short paragraphs that each add context. Minor redundancy: the 'look, don't conclude' caveat is stated twice in nearly the same words.

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 correctly carries the burden of describing what comes back (confidence-scored candidate matches, their provenance, and their inherent fallibility), plus the auth and certification prerequisites. Nothing essential 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 100%, so the baseline is 3, but the description adds conceptual meaning beyond the schema by explaining what a 'tree' match actually is (the duplicates behind conflations) versus a 'records' match (a lead toward a document).

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?

Opens with a specific verb and resource ('Read FamilySearch's own candidate matches for a tree person') and immediately distinguishes the two candidate sources, so an agent can tell this apart from search_records and compare_person without opening a 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?

Clearly explains when each collection mode applies and frames the output as a lead rather than a conclusion, which is real usage guidance. It does not, however, explicitly name an alternative sibling (e.g. search_records) or state when not to call this tool.

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 only cover readOnlyHint and openWorldHint; the description adds the crucial behavioral caveat that the tree is community-edited, that conflations of same-named people are common, that the result is 'a hint where to look, not evidence,' and that an access token is required. That is substantive context the structured fields do not carry.

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?

Four short paragraphs, front-loaded with what the tool does, followed by next-step routing, a data-quality caveat, and auth. All sentences earn their place, though the caveat paragraph could arguably be tightened.

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?

There is no output schema, and the description does describe the returned content ('names, sex and facts'), the reliability of that content, and the auth requirement. It is nearly complete, with only minor gaps such as return shape detail or error behavior for an invalid id.

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?

There is a single person_id parameter and schema coverage is 100%, with the schema itself supplying the format example ('K2ZP-VY1'). The description adds no further parameter meaning, so the baseline of 3 applies.

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 ('Read one person from the FamilySearch shared tree') and immediately scopes what it returns ('names, sex and facts'), which cleanly separates it from sibling readers like get_person_relatives, get_person_memories and get_person_sources.

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?

Gives explicit usage context ('Use it to find records') and names the concrete follow-up call ('get_person_sources on the same id is usually the next call, because it leads out of the tree towards a document'), plus a caution on how to treat the result. An agent knows both when and how to proceed.

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 only declare readOnlyHint and openWorldHint, so the description usefully adds the auth requirement ('Requires an access token'), the shape of each entry (contributor, timestamp, change, typed reason), and the community-edited nature of the tree. It does not cover pagination or log-length limits.

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 action in the first sentence, then context, then the prerequisite. The framing prose ('This is how you judge what you are looking at') is somewhat atmospheric, but each paragraph still carries distinct payload.

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 compensates by enumerating the fields of each log entry, and it flags the access-token prerequisite. For a single-parameter read tool, nothing an agent needs to invoke 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?

Only one parameter, person_id, and schema coverage is 100% with a format example ('K2ZP-VY1'). The description adds no further parameter meaning, so the baseline 3 applies – the schema carries this dimension entirely.

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: 'Read the change log of a tree profile: who edited it, when and why.' That is unambiguous and distinct from sibling reads like get_person or get_person_sources. It never names or contrasts a sibling, so it stops short of the top score.

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?

Gives a clear interpretive use case – judging how a profile was assembled and where a conflation likely entered – plus a concrete trigger (a name/parent changed recently with no reason). It also sets boundaries ('a hint where to look, not evidence... cite the record'). It does not name competing tools or state when not to call it.

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?

Goes well past the readOnly/openWorld annotations: it discloses that an access token is required, that contents are arbitrary user uploads of wildly varying evidentiary quality, and that the tree is community-edited with common same-name conflations. Those are exactly the operational caveats an agent cannot infer from structured fields.

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?

Purpose is front-loaded in the first sentence and the caveats are sequenced sensibly. It is somewhat long for a two-parameter read tool, and the 'recollection written down eighty years later' flourish is editorial rather than load-bearing, but most sentences carry information.

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 should say what a memory looks like when returned (metadata, links, whether download_image is needed to get the bytes). It covers content caveats and auth well but leaves the return shape entirely unexplained, which is a real gap for a tool whose whole job is retrieving media.

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%, with person_id format ('K2ZP-VY1') and the count range (1-100, default 25) already documented in the schema. The description adds no additional parameter meaning, so baseline 3 applies.

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: 'Read the photographs and documents attached to a tree person,' then concretizes what a memory actually is (headstone photo, scanned letter, Bible page, typed story). It never names the nearby sibling get_person_sources, which is the tool most likely to be confused with this one, so sibling differentiation is left to inference.

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 gives real guidance on how to treat the output ('look before relying on it', 'a hint where to look, not evidence: follow it to a record and cite that'), which is useful interpretive framing. But it never says when to choose this tool over get_person_sources, get_person, or the record/image tools, so tool-selection guidance is only 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?

Beyond the readOnly/openWorld annotations, it discloses that the tree is community-edited, that conflations are common, that results are a hint rather than evidence, and that an access token is required. This is exactly the reliability and auth context an agent needs before trusting the output.

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?

It is front-loaded with the function and then the cautions, and each paragraph earns its place. The conflation-detection narrative is slightly longer than strictly necessary but is substantive rather than 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?

With no output schema, the description carries the return burden and does so by enumerating the relation categories returned. Combined with the reliability caveat and auth requirement, an agent has everything needed to call and interpret this tool.

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?

There is a single parameter with 100% schema description coverage, and the schema already supplies the id format and an example. The description adds nothing about the parameter, so the baseline of 3 for a fully documented schema is correct.

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 verb and resource: reads a tree person's parents, spouses, children and siblings. The scope ('whole immediate family') distinguishes it from siblings like get_ancestry and get_descendancy, which walk full lines rather than the immediate circle.

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 gives clear context for use ('what you need to judge whether a profile is the person you are looking for') and explains what a mismatched family implies. It stops short of naming the alternative tools (get_ancestry, get_descendancy, compare_person) or the conditions that would select them.

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?

Goes well beyond the readOnlyHint/openWorldHint annotations: discloses the access-token requirement, warns the shared tree is community-edited with common conflations, and gives semantic guidance on interpreting empty or misaligned source lists. This is meaningful behavioral context an agent cannot get from 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?

Purpose is front-loaded in the first sentence and each subsequent paragraph carries real guidance rather than filler. It is somewhat editorial and longer than strictly necessary for a one-parameter read tool, which keeps it out of 5 territory.

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 compensates by explaining what an attached source contains (citation, ark, supported fact names), the auth requirement, and the reliability caveat. An agent has everything needed to call and interpret the tool.

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 fully documents the single person_id parameter (100% coverage, including a format example), so the description adds nothing parameter-specific. Per the rubric, full schema coverage means a baseline of 3.

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?

Opens with a precise verb+resource: 'Read the sources attached to a tree person.' The resource (attached sources with citations/arks) is clearly distinct from siblings like get_person_memories or get_person_changes, so an agent can route without opening any 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?

Gives strong context for why and when to call it ('the way out of it', follow a profile to actual documents) and how to interpret results ('a hint where to look, not evidence'). It does not explicitly name alternative tools or state when *not* to use it, so it stops short of a 5.

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 and openWorldHint, and the description adds the operationally useful 'Works without credentials' fact that the annotations do not convey. It also explains the semantic meaning of the returned dates, which is real domain behavior rather than a restatement. It stops short of describing response shape or any failure modes.

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 purpose is front-loaded in the first sentence, and the auth note is a compact, high-value line. The middle prose about counties 'in being' is slightly meandering, but it still earns its place by explaining why the dates matter.

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 one required parameter, full schema coverage, annotations carrying the safety profile, and an enumeration of returned fields (jurisdictional chain, type, coordinates, dates), the description is nearly sufficient for a single-item read. The main residual gap is disambiguation from the overlapping jurisdiction/children getters.

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% — the sole place_id parameter is fully documented in the schema, including an example and a note that place lookups return one on every result. The description adds no additional parameter meaning, so the baseline 3 applies.

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 with an explicit scope: 'Read one place: its jurisdictional chain, type, coordinates and dates.' That clearly separates it from the search_* siblings by cardinality. It never names an alternative, though, so the distinction from get_place_jurisdictions (which also returns a jurisdictional chain) must be inferred.

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 second paragraph gives a genuine research context ('check whether the county a record names was the county in being on the date the record was made'), which implies when the tool is valuable. However, there is no explicit when-not guidance and no routing among the several overlapping siblings (search_places, search_places_at_date, get_place_jurisdictions, get_place_children), leaving the agent to guess.

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 and openWorldHint, so safety is covered. The description adds real behavioral context beyond them: the direction of traversal relative to get_place_jurisdictions and the auth fact 'Works without a token'. It stops short of describing return shape or nesting depth, but for a read-only lookup the added context is substantial.

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?

Three short sentences, zero filler. The core action leads, the sibling contrast and the practical use cases follow, and the auth note is a brief trailing clause.

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 one-parameter read-only list tool with no output schema, the description covers purpose, direction, use cases, and auth. The main remaining gap is what the result set looks like (fields, depth semantics), which is not described, but the essentials for correct invocation are present.

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 a single documented place_id, so the schema already carries the parameter contract. The description adds only the notion that children are 'immediate' (one level down), which is modest value beyond the schema; baseline 3 applies.

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 ('List') and resource ('places directly inside a jurisdiction'), and explicitly frames itself against the sibling get_place_jurisdictions as the downward complement of that upward walk. An agent can distinguish the two traversal tools 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?

Gives concrete when-to-use scenarios: placing a town referenced in a record, and seeing what a county contained at a given time. It also names the complementary sibling and the directional relationship, so alternatives are explicit.

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 cover the safety profile (readOnlyHint=true) and open-world scope, so the bar is lower, yet the description still adds real value: it discloses the return ordering ('innermost first'), the per-level fields (id, type, span of existence), and the auth requirement ('Works without credentials'). It stops short of failure behavior for an invalid or top-level place_id.

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-loaded with the core action, then the concrete example, then the return shape, then the auth note. Every sentence carries information an agent needs; nothing is redundant padding.

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 does the work of describing the return structure (ordered chain of levels with id/type/span), which is exactly what's needed. Minor gap: it doesn't state edge-case behavior (e.g., a place that is itself a country, or an unknown place_id).

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?

Only one parameter and schema description coverage is 100%, so the schema already fully documents place_id as the 'FamilySearch place description id to walk upward from.' The description adds no syntax, format, or constraint beyond that, so the baseline 3 applies.

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 ('walk a place's containment chain upward to the country') and immediately grounds it with a concrete example ('Kaskaskia' → 'Kaskaskia, Randolph, Illinois, United States'). The explicit 'upward' direction contrasts cleanly with the sibling get_place_children, which walks the other way, so an agent can route 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?

Usage is implied by the mechanism ('walk upward to the country') but the description never says when to prefer this over get_place, get_place_children, or search_places_at_date, nor when it is not appropriate. No exclusions or prerequisites are stated beyond the credential note.

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 and openWorldHint, so safety is covered. The description adds genuinely non-structured context: it requires an access token, it returns the index rather than the document image, and it explains the 'original' transcription semantics and FamilySearch-supplied dates/places.

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-loaded with the core verb+resource, then layered detail. Some prose is deliberately literary, but the paragraphs each carry behavioral weight (fields vs summary, index vs document, auth). Slightly long for a one-parameter read tool but no dead sentences.

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?

No output schema exists, yet the description explains the return shape in detail: named persons, indexed fields with original transcriptions, value/date/place per fact. Combined with auth and read-only annotations, an agent has everything needed to invoke and interpret the result.

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% and there is a single required `ark` parameter, so the schema already carries the format and example. The description adds only the fact that record searches return one ark per hit, which is already implied in the schema description.

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 ('Read one indexed record in full') and sharply distinguishes itself from search_records (which returns 'a persona'/summary) and from get_record_image ('still the index, not the document'). An agent can route without opening a 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?

Clearly frames the use case versus search (details the search summary loses) and names get_record_image as the alternative for reaching the original document. It does not spell out an explicit 'do not use this when...' exclusion, but the routing context is unambiguous.

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 cover only read-only and open-world. The description adds genuinely useful behavioral context on top: it discloses the auth prerequisite ('Requires an access token') and the important negative-result behavior ('many records carry no image link at all, in which case this says so rather than inventing one'), plus what the payload contains (image/waypoint links, DGS and image numbers).

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 operative sentence is front-loaded, and the paragraphs on missing image links and the token requirement each carry functional weight. The 'persona is somebody's reading of the record' passage is more flavor than instruction and could be trimmed, but it does justify the verify-against-film usage.

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 steps in to describe the return shape (image/waypoint links, DGS and image numbers) and the common no-link case. Combined with the auth note, an agent has everything needed for a one-parameter read tool.

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% and there is a single parameter, so the schema already documents 'ark' adequately. The description adds no format, encoding, or lookup nuance beyond the schema's 'Record ark or id', so the baseline 3 applies.

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 opening sentence gives a specific verb and resource with the direction of the relationship baked in ('the document image an indexed record was taken from'), which is exactly what separates it from the reverse-direction sibling get_records_on_image and from the retrieval siblings get_film_image/download_image. An agent can tell what this returns without opening the 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?

Clear context: use it to verify an indexed reading against the actual image ('anything that matters should be checked against the film'), and it tells the agent what to do when no image exists (read the citation, order the film). It stops short of naming alternative tools such as get_film_image or download_image, so there is no explicit when-not routing.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond that: the access-token requirement and the expected result size (thirty to forty records per page), which helps an agent anticipate a bulk list rather than a single record.

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-loaded with the core action and the reverse-of relationship, and the auth note is placed last. The middle paragraph's manifest/census illustration earns its place by explaining why a bulk list is useful, though it is slightly more verbose than strictly needed.

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 single-parameter, read-only list tool with no output schema and annotations already covering safety, the description covers what it returns, the auth prerequisite, and the practical use cases. An agent has enough to invoke it correctly; only formal exclusions for when not to use it are 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 100% and the single parameter (image_ark) is fully documented with an example in the schema. The description only restates 'one image' and adds no syntax or format detail, so baseline 3 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?

States a specific verb and resource ('List every record indexed from one image') and explicitly positions itself as the reverse of the sibling get_record_image, so an agent can distinguish the two directions of the image/record relationship 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?

Gives concrete when-to-use scenarios: picking up a whole household from a page, or verifying whether a person was indexed at all. It does not state when NOT to use it or name an alternative for single-record lookup, so it falls short of the full 5.

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 and open-world, so the safety profile is covered; the description goes well beyond by disclosing caching behaviour ('first call reads the whole catalogue and caches it'), catalogue freshness metadata, whole-word matching semantics including the inside-a-word fallback, and that it works without a token. These are operational traits an agent cannot infer from annotations or schema.

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 purpose, then workflow value, then caveats; each paragraph carries a distinct concern (matching, coverage statement, caching, auth). A few sentences are stylised ('a fishing expedition into a lookup') and cost more words than needed, but no sentence is pure 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?

No output schema exists, so the description must carry the return contract — and it does: each result carries a coverage statement (record types, place, years) and the catalogue reports its own size and age. Combined with the staleness warning and the no-token note, an agent has everything needed to call and interpret the result.

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. The description still adds meaning beyond the schema: matching is whole-word against title with an inside-a-word fallback, an empty query browses rather than filters, and refresh implies a ~two-minute uncached catalogue read whose cost and staleness trade-off is spelled out.

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 ('Find a record collection') plus its role in the workflow ('so a search can be scoped to one'). The second paragraph distinguishes a collection from its siblings — it is the unit that search_records filters on — so an agent can separate it from get_collection (single fetch) and search_records (the consumer) without opening a 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?

Explicitly names when to use it (to obtain a collection id to scope search_records) and the value of doing so ('turns a fishing expedition into a lookup'). It also gives the precondition for the refresh alternative ('needed when looking for a collection published since the catalogue was fetched, or when it is incomplete'), which is a when-to-use-this-option rule rather than a restatement.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond that: it works without credentials, and it discloses the shape of what comes back (place id, coordinates, jurisdictional form), which matters since there is no output schema. Minor gap: no mention of result limits or ambiguity behavior when a name is ambiguous beyond the 'count' parameter already in the schema.

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?

Four tight paragraphs, each front-loaded with its key point: purpose, disambiguation from the dated variant, downstream usage, and credential requirement. No sentence is redundant and the most decision-relevant routing advice comes early.

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 two-parameter read tool with no output schema, the description compensates by describing the returned payload (place id, jurisdictional form, coordinates) and the sibling routing. An agent has everything needed to call it and chain its output correctly.

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%, with both 'name' and 'count' documented inline, so the baseline is 3. The description adds no syntax, formatting, or matching-semantics detail beyond what the schema already provides.

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 ('Look up a place in the FamilySearch gazetteer') and immediately clarifies the transformation performed: resolving a bare name to full jurisdictional form plus coordinates. This distinguishes it from siblings like get_place, which consumes the resolved id rather than producing it.

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 names the alternative (search_places_at_date) and the condition selecting it ('if the place name comes from a record with a date on it'), and explains why (jurisdictions change). It also states the natural downstream tools get_place and get_place_jurisdictions, completing the workflow guidance.

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?

With readOnlyHint and openWorldHint already declared, the description still earns credit by adding auth context ('Works without credentials') and by describing the shape of results ('Each result carries the span over which that jurisdiction existed'), which matters because no output schema exists. It stops short of saying how many results to expect or how ambiguity is signalled beyond the within_place_id hint.

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 core operation is front-loaded in the first sentence, and the remaining paragraphs are rationale rather than filler — they explain the failure mode the tool guards against. It is a touch discursive at roughly 140 words for a four-parameter lookup, but nothing is purely decorative.

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 read-only, open-world lookup with full schema coverage and no output schema, the description covers the essentials: what is resolved, which inputs matter and in what form, that no credentials are needed, and what each result contains. An agent has everything required to invoke it correctly.

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%, including the important 'use the year of the record, not today' note on year and the narrowing role of within_place_id, so the baseline of 3 applies. The prose reinforces the name/year convention but adds no syntax, format, or edge-case detail beyond what the schema already carries.

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 opening sentence gives a specific verb (resolve), resource (place), and a temporal scope (as it existed in a particular year) that cleanly separates it from the modern-place siblings search_places and get_place. However, it never names those siblings, so the agent has to infer the routing distinction rather than being told.

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 gives concrete operating guidance: pass the name as the record spells it, use the year of the record rather than today, and avoid filing an old record under the modern county. That is clear when-to-use context, but it stops short of explicitly naming an alternative tool for modern-name lookups, so there is no true when-not.

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 cover only readOnlyHint and openWorldHint, and the description adds substantial non-obvious behavior: default filters are loose (missing fields still match, name variants match, years match within 5, places widen), exact flips that to strict conjunctive matching, and the result's `filters` field reports exactly/relaxed/ignored — with an explicit warning not to treat a nil result as a negative. It also states the access-token requirement, which no annotation conveys.

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-loaded with purpose, then structured into relationship/scoping guidance and a filtering-semantics paragraph. Nearly every sentence carries information, though the middle prose is dense enough that it reads more like documentation than a terse tool blurb.

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 21-parameter, no-output-schema, mutation-free search tool with thin annotations, the description covers what matters most: the implicit name requirement, the token prerequisite, the loose-by-default filtering model, and where to inspect applied criteria in the response. Nothing an agent needs 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 coverage is already 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema lacks: the relationship-criteria use case, the archive-vs-register effect of record_type/collection_id, and the precise matching semantics of `exact` versus default loose filtering. It also states the at-least-one-name requirement that the schema (0 required params) does not enforce.

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?

Opens with a specific verb and resource plus the five facets it searches (name, events, relatives, type, collection). This distinguishes it cleanly from siblings such as fulltext_search, get_record, and search_collections without the agent needing to open any 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?

Gives concrete when-to-use cases: relationship criteria recover a man misindexed under his wife's or father's name, and scoping to a type or collection narrows the archive to one register. It also explains when to turn on exact ('to bound a negative or cut noise'). It stops short of naming sibling alternatives like fulltext_search for text-heavy queries, so routing is implied rather than explicit.

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