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

Annotations only declare readOnlyHint and openWorldHint, and the description adds substantial context beyond them: it clarifies that `authenticated` merely means a token is set while `token_accepted` reflects a live FamilySearch check, notes the ~1 hour token lifetime, and discloses that the server ships no client id. This is exactly the extra behavioral detail the annotations cannot convey.

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 purpose is front-loaded in the first sentence, followed by clarifying details and a docs pointer. It is appropriately sized for a small diagnostic tool, though the three-paragraph layout is slightly more than strictly necessary.

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 no parameters, the description carries the burden of explaining the return semantics, and it does so by defining `authenticated` vs `token_accepted`, the token lifetime, and the client-id prerequisite. An agent has everything needed to interpret and act on 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?

The tool takes zero parameters, so the schema provides the full parameter picture and the description has nothing to add. The baseline for a parameterless tool applies, with no compensating gap to fill.

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: it reports whether credentials are configured and what is missing, and further names the two returned signals (`authenticated`, `token_accepted`). This is plainly distinguishable from every sibling, which all fetch genealogy data rather than report auth state.

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 implies this is a diagnostic check but never states explicitly when to call it (e.g. before other tools, or after an auth failure) or how it relates to sibling tools. It does supply the prerequisite that production access requires your own registered FamilySearch application, which nudges usage, but there are no when/when-not directives.

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 auth context beyond the annotations ('Works without a token') and discloses the stateful, multi-call traversal pattern, which is genuinely useful. It stops short of describing return contents or any throttling.

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, followed by the rationale and then the mechanics, with no filler sentences. The prose is slightly literary ('may still be sitting on an image you can browse to') but each sentence contributes actionable 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 carries the return-shape burden and partially does so by explaining that children contain waypoint_ids used to descend. For a two-parameter, annotation-covered read tool this is nearly complete, though a note on what a leaf page yields would close the loop.

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 parameters are already fully documented in the schema, including the instruction to take waypoint_id from a previous call's children. The description restates the top-down descent but adds no format, example, or constraint beyond that, 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 opening sentence gives a specific verb and resource ('Browse a collection's structure') and enumerates the levels involved (volumes, date ranges, films). It implicitly distinguishes itself from the searching siblings by framing itself as the route to material the index missed, so an agent can tell it apart 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?

It states the selecting condition explicitly: indexing is incomplete, so anything not found via search may still be reachable by browsing. It also gives the call sequence — 'Pass a collection_id to start, then a waypoint_id from the children to descend' — which is exactly how an agent needs to operate 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 flag readOnly=false, idempotent=false and openWorld=true; the description goes well beyond them by explaining the write-to-disk rationale, that existing files are never overwritten, that only FamilySearch URLs are fetched because the request carries the access token, and that content may be copyrighted or access-restricted. This is exactly the kind of context annotations cannot express, and it is consistent with idempotentHint=false.

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, each front-loaded with its point: what it does, why the file is on disk, what URLs are permitted, and the copyright caveat. No sentence is filler; every one carries distinct 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?

For a mutation-style tool with no output schema, the description covers side effects (file written, never overwritten), authorization (FamilySearch token scope) and legal caveats (copyright). It does not say what the tool returns on success, which is a minor gap given an agent may want confirmation of the written path.

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 parameters (image_url, destination) are already fully documented with examples and constraints. The description adds no parameter-level syntax or format detail, 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 — download a document image to a local file — with the intent (so it can be read) made explicit. It distinguishes itself by framing this as the terminal evidence step, though it only implicitly separates itself from siblings like get_image_links and get_film_image, which the input schema names as the URL 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?

Clear context is given: this is the step that turns a citation into evidence, implying it follows a link-retrieval call, and the schema explicitly points at get_image_links/get_film_image as the URL origin. No explicit when-not or direct sibling comparison beyond that, 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 only declare readOnly and openWorld; the description adds substantial context beyond that: the Ahnentafel numbering scheme, the reliability caveat that deep pedigree lines are frequently copied, the community-edited nature of the shared tree with common conflations, and the explicit auth requirement. This is rich behavioral disclosure 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-loaded with the core action, then progressively adds the numbering key, reliability warning, and auth note. Each paragraph earns its place, though the pedigree-suspicion paragraph is slightly expository for a tool definition.

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 100% parameter coverage, the description carries the return-shape burden and does so: it explains the flat list with Ahnentafel gaps, the reliability of results, and the access-token requirement. An agent has everything needed to call and interpret it.

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. The description adds genuine meaning by explaining the Ahnentafel numbering (person=1, father/mother=2/3, grandparents=4-7), which makes the 'generations' parameter and the flat-list output interpretable. It stops short of discussing the 1-8 bound rationale.

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: walking a person's pedigree back through generations. The Ahnentafel explanation makes the output shape concrete. It does not explicitly name the sibling it contrasts with (get_descendancy), though 'back' implies direction, 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?

The description clarifies what the result is for ('a hint about where to look, not evidence' and to cite an underlying record instead), which implies usage context. However it never states when to prefer this over get_descendancy, get_person_relatives, or get_person, leaving alternative selection to inference.

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 context beyond the readOnlyHint/openWorldHint annotations: 'Works without a token' discloses the auth requirement, and the note about image count versus record count gives interpretation guidance for the returned counts. It does not describe pagination or response shape, but that is largely covered by the single-record scope.

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 supporting usage and interpretation notes. Slightly conversational ('how much of it there is') but every sentence carries information; no wasted text.

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 tool with no output schema, the description compensates by explaining what the returned counts mean and the heuristic for a low image-to-record ratio. The auth note fills another gap. Only minor omissions (return structure) remain.

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 parameter is fully documented in the schema, including example format and where search_collections yields values. The description adds no parameter-level 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 ('Read') and resource ('one record collection') and immediately scopes what is returned ('what it covers, and how much of it there is'). This distinguishes it from the sibling search_collections, which the schema note also references, so an agent can route correctly 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 a clear use condition: 'Worth reading before trusting a nil result,' which tells the agent when this tool is valuable. It does not explicitly state when not to use it or name the sibling alternative, but the implicit contrast with search_collections is reasonably 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 already declare readOnlyHint=true and openWorldHint=true. The description adds a non-obvious behavioral fact that annotations don't cover: it 'Works without a token,' which tells the agent no auth is needed. It doesn't describe return structure in depth, but with annotations covering the safety profile this is solid.

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 code examples plus the 'read before interpreting' guidance each earn their place. Slightly long across four short paragraphs, but nothing is redundant.

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 exactly what the tool returns (a code-to-label dictionary) and why the agent would need it. Combined with the schema's parameter documentation, an agent has everything required 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 description coverage is 100%, and the schema itself documents collection_id with an example ('1417683' for the 1880 US census) and a pointer to search_collections. The description only conceptually frames what a collection is, so the baseline 3 for high-coverage schemas 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 ('Decode') and resource ('the field codes a collection's indexed records use'), then concretely illustrates the codes with examples like PR_FTHR_NAME and their decoded meanings. An agent can immediately distinguish this from get_collection or get_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?

Explicitly says 'Read it before interpreting a record from a collection you have not worked with,' which names the trigger condition. It also points to search_collections for finding the collection id, connecting to the sibling that supplies the input.

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 readOnly and openWorld, but the description adds real behavioral context beyond them: living descendants are withheld and returned as restricted, the tree is community-edited with common same-name conflations, results are a hint not evidence, and an access token is required.

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, each front-loaded with its point: what it does, why to use it, what comes back withheld, and the data-quality caveat. No sentence 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 carries the return-value burden and does so, explaining that restricted living descendants are marked and that results are probabilistic hints. Annotations cover the safety profile, and auth requirements are stated.

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 1-4 range and the fan-out rationale. The description adds no parameter detail beyond that, 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 ('Walk a tree person's descendants forward through the generations') with a clear directional scope that separates it from the sibling get_ancestry. An agent can tell what it 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?

Gives a concrete use case ('the sideways search' when a person's own record cannot be found) and frames the output as a hint rather than evidence. It never names an alternative tool or an explicit when-not condition, so it stops just short of full routing 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?

Annotations only declare readOnlyHint and openWorldHint, but the description adds real behavior: it checks the thumbnail first and plainly reports whether the image exists, so bad numbers yield a clear answer rather than a failing URL. It also discloses the auth requirement — thumbnail is readable without a token, the full page needs one.

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 every remaining sentence adds routing or behavioral value. It is a bit loose and multi-line, but no sentence 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 carries the return burden and does explain the existence-check behavior and token distinction. It stops short of detailing exact return contents, but for a read-only image locator it is nearly complete.

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 good per-field descriptions, so the baseline is 3. The description adds provenance value by naming the source fields (FS_DIGITAL_FILM_NBR, FS_IMAGE_NBR) on indexed records, helping the agent know where to obtain the values.

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+resource ('Reach a page image') and a distinctive access path ('by film and image number instead of by ark'). It explicitly distinguishes itself from the siblings get_image_links and get_record_image, so an agent can disambiguate 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?

Explicitly says when to use it (citations name film+image, not an ark) and names the alternatives it is not: get_record_image reports the numbers, and get_image_links cannot help because there is no ark. This is explicit when/when-not/alternatives coverage.

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 value beyond that: it enumerates what comes back (storage node, deep-zoom descriptor, multiple thumbnail sizes, full-resolution page, neighbour pages), which matters since there is no output 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-loaded with the core action and return contents; the trailing sentence about pension files and manifests earns its place by justifying the neighbour-page behaviour, though it is the wordiest part of an otherwise tight definition.

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 burden and does it well, and annotations cover the read-only/open-world profile. Nothing needed to call this tool 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 with 100% schema coverage, and the schema itself supplies the precise provenance rule for image_ark. The description adds no format or sourcing 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 contrasts itself with a record read. It does not distinguish itself from image-related siblings like get_record_image, get_film_image, or download_image, so an agent still has to guess among those.

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 trigger condition — you need this when a record read lacks image links and the image resource carries them — and explains why neighbouring pages matter. It stops short of naming alternatives (e.g. when to prefer download_image), so 'when not to use' is absent.

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=true and openWorldHint=true, but the description adds substantial behavioral context beyond them: it requires an access token, restricts record matches to certified applications (refusal otherwise), warns that the shared tree is community-edited with common conflations, and emphasizes the output is a hint, not evidence.

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 and well-structured, but contains redundancy: the warning about not concluding is stated twice ('a high score is a reason to look, never a reason to conclude' and 'a hint about where to look, not evidence'). The conflations caveat also appears more than once. Trimming these would improve conciseness.

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 no output schema, the description conceptually explains what is returned (candidate matches with confidence scores) and covers critical caveats like access token requirement, production restrictions, and data reliability. It does not describe the response format or pagination behavior, but the conceptual coverage is strong for a 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 coverage is 100%, so baseline is 3. The description adds meaning about the 'collection' parameter by elaborating on what 'tree' duplicates represent (conflations, same person with different parents) and that 'records' are leads to documents. It doesn't add detail for 'count' or 'person_id' beyond the schema.

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 FamilySearch's own candidate matches for a tree person') and distinguishes between the 'tree' and 'records' collections. It clearly sets this tool apart from siblings like get_record by framing the results as system guesses, not evidence, which is a unique scope.

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?

Provides clear context for when results are useful ('a high score is a reason to look, never a reason to conclude') and points to the alternative ('Follow it to an underlying record and cite that instead'). It also notes a production restriction for record matches. However, it does not explicitly state when to prefer this over search_records or get_person_sources.

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: it warns the tree is community-edited, that conflations of same-named people are common, that returned data is a hint rather than evidence, and that an access token is required. This is exactly the caveat 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?

Front-loads the core action, then layers returns, workflow, caveats, and auth in short, distinct paragraphs. No sentence is redundant and each adds a decision-relevant fact.

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 describing returns ('names, sex and facts'), and it also supplies the data-quality caveat and auth requirement. An agent has everything needed to call it and interpret the result cautiously.

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 person_id parameter already carries a format example ('K2ZP-VY1'). The description adds no further parameter syntax or 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 ('Read one person from the FamilySearch shared tree') and enumerates the returned content (names, sex, facts). It also names a sibling workflow (get_person_sources), letting an agent place it among the many get_*/search_* 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?

Provides clear usage context ('use it to find records') and routes the agent to the usual next call, get_person_sources on the same id. It stops short of an explicit when-not-to-use rule versus siblings like get_record or search_records.

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 readOnly and openWorld, but the description adds substantial context beyond them: it requires an access token, warns the tree is community-edited with common same-name conflations, and frames the output as 'a hint about where to look, not evidence.' It also describes the per-entry fields (contributor, timestamp, change, reason).

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 in the first sentence, then layers interpretation guidance and caveats. Every section is relevant, though the multi-paragraph framing is somewhat expansive for a single-parameter read tool.

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-shape burden and does so by describing each entry's contents. It also covers auth requirements and the epistemic caveat about the data, leaving no major gap for calling the 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?

Only one parameter with 100% schema coverage that already documents the FamilySearch person id format ('K2ZP-VY1'). The description adds no syntax or value 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: 'Read the change log of a tree profile,' and immediately enumerates the payload ('who edited it, when and why'). This clearly differentiates it from get_person, get_person_sources, and get_person_memories among the siblings.

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 analytical purpose (judging how a profile was assembled, spotting recent unreasoned name/parent changes where conflations enter) and directs the agent onward: 'Follow it to an underlying record and cite that instead.' It frames when the tool is valuable but never names a sibling alternative explicitly, 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, yet the description adds substantial context: memories are uploads of highly variable reliability, the tree is community-edited with frequent conflations, results are hints not evidence, and it requires an access token. This is meaningful behavioral disclosure beyond the 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 and keeps each paragraph purposeful (what memories are, reliability caveat, community-edit caution, auth). It runs somewhat long for a two-parameter read tool, with mild redundancy between the 'look before relying' and 'hint not evidence' 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?

With no output schema, the description characterizes the returned content (uploaded photographs/documents of mixed evidentiary value) and the auth requirement. It does not describe response structure or pagination, a minor gap for a parameterized 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% for both parameters (count with range/default, person_id with format example), so the schema does the work. The description adds no parameter-specific syntax or semantics, making the baseline 3 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?

Opens with a specific verb and resource: 'Read the photographs and documents attached to a tree person,' and clarifies the resource is user uploads (memories). This distinguishes it from sibling tools like get_person_sources (records) and get_person (profile data) 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?

Gives strong interpretive guidance ('look before relying on it,' 'follow it to an underlying record and cite that instead'), which steers the agent toward get_record/search_records. It does not explicitly name which sibling to use when, so it falls short of the 5-level 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?

Goes well beyond the readOnly/openWorld annotations by disclosing that the shared tree is community-edited, that conflations of same-named people are common, that the result is a hint rather than evidence, and that an access token is required. This is exactly the behavioral context an agent needs before treating the output as authoritative.

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 operation, then supporting context. Multi-paragraph, but each paragraph earns its place (scope, purpose, data-quality caveat, auth). Slightly longer than strictly necessary for a one-parameter read tool.

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 suitably names what is returned and frames it as a hint not evidence, plus the auth requirement. It is nearly complete; only the concrete shape/fields of the response are 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?

Only one parameter exists and the schema documents it fully (100% coverage, including an example ID format). The description adds no syntax or format detail 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 ('Read') and an exact resource scope: parents, spouses, children, siblings. This distinguishes it clearly from sibling extended-lineage tools like get_ancestry and get_descendancy, which pull wider trees.

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 context of use well: one call for the whole immediate family, used to judge whether a profile is the intended person, with concrete mismatch signals. It does not explicitly name an alternative tool for extended family, so it stops short of a true 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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the auth requirement ('Requires an access token'), the community-edited nature of the shared tree, the resulting conflation risk, and the critical framing that output is 'a hint about where to look, not evidence.' That is exactly the kind of behavioral 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?

The core action is front-loaded, but the description runs several paragraphs with rhetorical filler ('the most useful thing in the tree, because it is the way out of it') around genuinely useful caveats. Some of the length does not earn its place for a one-parameter read tool.

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 each source carries (a citation, usually an ark to an indexed record) and the per-source 'supports' fields (Name, Birth, Death). That is enough for an agent to interpret the return value without a schema.

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 parameter (person_id), so the schema already documents the input. The description adds nothing about the parameter, 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?

Opens with a specific verb+resource: 'Read the sources attached to a tree person.' It clearly distinguishes sources from the facts a profile holds, which separates it conceptually from get_person. However, it never names a sibling tool, so differentiation is implicit rather than 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?

Gives clear context for why and when to use it ('the way out of' an unsupported profile) and directs the agent onward to an underlying record to cite instead, implicitly pointing at get_record. It stops short of stating when-not-to-use or naming concrete alternatives by name.

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 context the annotations do not: that the tool 'works without credentials,' which is notable in a toolset that includes auth_status, plus an explanation of what the returned dates represent. It stops short of describing error behavior or lookup-miss handling.

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 sentence one and the whole thing stays short. The middle paragraph is slightly discursive for a one-parameter read tool, but each sentence contributes distinct information (why the dates matter, credential requirement) rather than restating the schema.

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 describing return content, and it does list the returned facets (jurisdictional chain, type, coordinates, dates). It also flags the no-credentials property. Minor gaps remain around date formatting and behavior for an unknown place_id, but nothing essential for invoking the tool 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?

With a single parameter at 100% schema description coverage, the schema already explains that place_id is a FamilySearch place description id with an example and where to obtain one. The description adds no syntax or sourcing detail beyond that, 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?

The first sentence states a specific verb (Read), resource (one place), and enumerates what comes back: jurisdictional chain, type, coordinates, dates. That is enough for an agent to know what the tool returns. It does not, however, differentiate itself from close siblings like get_place_jurisdictions or get_place_children, which also touch jurisdictional data.

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 middle paragraph supplies a genuine use rationale (checking whether a county named on a record existed on the record's date), which implies when the tool is worthwhile. But it names no alternatives and gives no explicit when-not-to-use guidance against search_places, search_places_at_date, or get_place_jurisdictions. Usage is implied rather than specified.

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) and openness (openWorldHint), so the bar is lower, and the description still adds an auth-relevant fact: it works without a token. It stops short of describing return shape or any size/pagination behavior, which keeps it from a 5.

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 layered with the sibling contrast and use cases. Every sentence earns its place and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with no output schema and safety annotations already present, the definition covers purpose, direction, and auth adequately. It could say more about the returned hierarchy depth or format, but nothing needed 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?

Single required parameter with 100% schema description coverage including an example value ('442'), so the schema carries the semantics. The description adds no further meaning about what a place_id is or where to obtain it; 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 ('List the places directly inside a jurisdiction') and immediately frames its scope against the sibling get_place_jurisdictions by naming the opposite traversal direction. An agent can distinguish it from every other place-related sibling 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?

Gives two concrete when-to-use scenarios (placing an unlocatable town, seeing a county's historical contents) and explicitly names the complementary tool it contrasts with. The selection condition versus get_place_jurisdictions is stated, not inferred.

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=true and openWorldHint=true, so the safety profile is already covered. The description adds useful behavioral context beyond annotations: it says the chain is returned innermost first, each level carries id/type/span, and that the tool works without 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?

The description is front-loaded with the core operation and is compact for the amount of useful detail it provides. The example and credential note earn their place, though the line breaks make it slightly less tight than 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 must explain what comes back, and it does: an ordered chain, innermost first, with id, type, and span at each level. It also notes credential-free operation. Remaining gaps—error behavior or exact span semantics—are minor for an agent that mainly needs to know what the call returns.

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 is fully documented as a FamilySearch place description id. The description adds an illustrative example of what the walk produces but does not add syntax or format details beyond the schema, so the baseline of 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?

The description states a specific verb and resource: 'Walk a place's containment chain upward to the country.' The example 'Kaskaskia' → 'Kaskaskia, Randolph, Illinois, United States' makes the operation concrete and distinguishes it from downward-looking siblings such as get_place_children.

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 implies when the tool is useful—when you need the full jurisdiction chain above a place—but does not explicitly name alternatives like get_place or get_place_children, nor does it state when not to use this tool. Usage is inferable but not fully guided.

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 context beyond that: it requires an access token, and it is the index rather than the document, so an agent won't over-trust the data as primary-source truth.

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 each sentence adds a distinct point (what it returns vs search, the fields' value, index-not-document, auth). Somewhat prose-heavy and could be tighter, but no sentence is wasteful.

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 carries the return-value burden and does so well, describing the per-person named fields labelled by source box. Combined with the auth and index-vs-document notes, 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 description coverage is 100% and the single 'ark' parameter is fully documented in the schema, including both accepted formats. The description adds nothing about the parameter, 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?

Opens with a specific verb+resource and scope ('Read one indexed record in full'), then explicitly contrasts it with search results and with get_record_image. An agent can distinguish it from search_records and get_record_image 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?

Explicitly routes the agent: use search to get summaries, use this to get the full indexed fields, use get_record_image when the original document is needed. Names the alternative (get_record_image) and the condition that selects 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?

With readOnlyHint/openWorldHint already covering safety, the description adds real value: it states the return contents (image/waypoint links, DGS and image numbers), discloses that many records return no link rather than a fabricated one, and notes the access-token requirement. It stops short of describing failure modes or response shape specifics.

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, but the middle paragraph is prose-heavy (indexer mis-reads, normalised spellings, unpublished microfilm) for a single-parameter lookup. The context is genuinely useful but not tightly compressed.

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-param read tool with no output schema, the description covers the return payload, the important edge case of missing images, and the auth requirement. An agent has everything needed to call it and interpret a null-ish 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?

Only one parameter (ark) and schema coverage is 100%, so the schema fully documents it. The description adds no syntax or format detail beyond what the schema already says, 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?

Opening sentence gives a specific verb+resource ('find the document image an indexed record was taken from'), which is clear. It doesn't explicitly distinguish itself from close siblings such as get_image_links, get_film_image, or download_image, which an agent could confuse it with, 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?

It explains the motivating use case (verifying indexer errors against the actual image) and tells the agent what to do when no image exists (read the citation and order the film). It does not name sibling tools or say when to prefer them, so no explicit alternative 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=true and openWorldHint=true, so the safety profile is covered. The description adds an auth requirement ('Requires an access token'), which is genuinely useful context, but says nothing about result size, ordering, or pagination for a list that could return dozens of records.

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 in one sentence, then adds motivation via the manifest/census example. The example sentences are a little elaborate but earn their place by justifying the tool's existence.

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 read tool with annotations covering safety and no output schema, the description supplies purpose, inverse relationship, use cases, and auth requirement. Only pagination/result-size behavior 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, image_ark, and schema description coverage is 100%, so the schema already documents its type and format ('3:1:33SQ-G5LD-93NY'). The description's 'one image' adds only a restatement of the input's role, not new syntax or constraints.

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 frames itself as the inverse of the sibling get_record_image. An agent can distinguish it from get_record 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 scenarios where this beats alternatives: recovering a whole household as a cluster, or verifying whether a target person was indexed from a page already in hand. It does not state explicit exclusions, but the positive guidance is clear and tied to sibling tools.

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 readOnly/openWorld annotations by disclosing that FamilySearch offers no catalogue search, that this walks the catalogue in ~90-record page blocks, that the first call makes several API requests, that results are cached, and that refresh costs about ninety seconds. It also notes it works without a token, which is operationally important. Missing only response-shape details, though those are partly covered by the coverage-statement description.

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 purpose and the payoff, with no filler sentences; every paragraph adds a usable fact (purpose, coverage reasoning, mechanics, auth). It is longer than strictly necessary and slightly essayistic, but the length is justified by the tool's non-obvious catalogue-walking behavior.

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 proactively explains what a result contains (a coverage statement: record types, place, years) and how to interpret it. Combined with the caching, paging, and auth notes, an agent has everything needed to call this correctly and reason about the 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 already 100%, so the baseline is 3, but the description adds real meaning: it clarifies that query words are matched against collection titles and that an empty query means browsing everything, which is more than the schema's 'leave empty to browse' phrasing conveys. The refresh/caching semantics are reinforced rather than merely repeated.

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 gives a specific verb (find) and resource (record collection) plus its downstream purpose ('so a search can be scoped to one'). It concretely distinguishes the tool from get_collection (fetch one by id) and search_records (search within one) by explaining the catalogue-walking match against titles.

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 states when to use it (once you know which collection should hold an entry, scope search_records to its id) and supplies the key prerequisite mental model: read the coverage statement, because a 1850-1900 collection cannot answer an 1840 question. It even distinguishes the meaning of a nil result depending on scoping.

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 a genuinely non-obvious behavioral fact not present in the annotations: 'Works without credentials,' which changes whether an agent needs to authenticate first. It stops short of describing result ordering or pagination, but the credential disclosure is real added value.

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 sentences, front-loaded with the core purpose, then the follow-up targets, then the dated-name caveat, then the credential note. No sentence 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 compensates by stating what each result carries (full jurisdictional form, coordinates, a place id) rather than enumerating fields. Combined with the credential note and the sibling routing, an agent has everything needed to call this 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% and both parameters (name, count) are documented in the schema, so the baseline is 3. The description clarifies what a 'name' resolves to semantically (bare name to full jurisdictional form plus coordinates), but adds no syntax, format, or matching-behavior detail beyond that.

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 explains what resolution produces: full jurisdictional form and coordinates. It is immediately distinguishable from get_place (which consumes a place id) and search_places_at_date (the dated variant).

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 and the condition that selects it: 'If the place name comes from a record with a date on it, prefer search_places_at_date.' It also tells the agent what to do with results (pass the place id to get_place or get_place_jurisdictions), closing the workflow loop.

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 safety (readOnlyHint) and scope (openWorldHint), so the bar is lower. The description still adds real value beyond them: it discloses that each result carries the jurisdiction's existence span, and that the tool 'works without credentials,' which is not captured in 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 purpose is front-loaded in the first line, followed by justification and call instructions. The middle paragraph on jurisdiction instability is longer than strictly needed to invoke the tool, but it does earn its place by explaining the failure mode the tool exists to prevent.

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, and the description compensates with a short statement of what results contain (the jurisdiction's existence span). The required inputs and the auth-free mode are both covered, leaving little an agent needs that is absent.

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 four parameters, including the year-of-record convention and within_place_id narrowing. The description reinforces the 'name as the record spells it' intent but adds no syntax or format detail beyond the schema, matching the baseline 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?

The opening sentence states a specific verb and resource with a temporal qualifier: 'Resolve a place as it existed in a particular year.' That temporal-resolution framing distinguishes it from plain lookups like search_places or get_place without needing to name them.

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 when-to-use guidance ('Give it the name as the record spells it and the year of the record') and warns against a specific misuse (filing under the modern county). It stops short of naming an alternative sibling tool for the non-temporal case, so it falls one step below explicit 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 cover the safety profile (readOnly, openWorld), so the description adds context beyond them: it discloses the access-token requirement and explains why fuzzy matching is the default and when exact becomes necessary. It does not describe result ordering or paging behavior, but the auth and matching-behavior disclosures are meaningful additions.

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 splits into named sections (Relationship criteria, Scoping) with the mandatory rule last. The 'Chesebrough'/'Mary' anecdote is slightly padded but illustrates a real edge case. Overall tight for the amount of guidance conveyed.

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, zero-required search with no output schema, the description supplies the missing decision framework and the auth prerequisite. It leaves pagination and result shape unstated, but those are minor against the strategic guidance it does provide.

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 parameter docs already carry the load; baseline would be 3. The description adds strategic meaning on top by framing two whole parameter families — relationship criteria (spouse/father/mother names) and scoping (record_type, collection_id) — explaining why an agent would use them rather than just what they are.

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 ('Search historical records') and enumerates the criteria axes (name, events, relatives, type, collection). It distinguishes itself from get_record by being a search, but does not explicitly differentiate from sibling searches like search_collections or search_places, which is where an agent could plausibly misfire.

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 real strategic guidance: use relationship criteria when the subject's own name was misindexed, and scope by type/collection to narrow to a single register. 'Pass at least one name. Everything else narrows.' is a clear usage rule. It stops short of naming alternative sibling tools to prefer in other cases.

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