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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and locality are covered structurally. The description adds the audit categories and confirms the output is a prioritized to-do list, but says nothing about how the `limit` caps findings, whether long trees are truncated, or reporting format.

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?

One dense sentence, front-loaded with the verb and resource, then the finding categories and the outcome. No filler, though the parenthetical example list is long enough to blunt the front-loading slightly.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. Still, a 4-parameter tool with an unexplained `limit` and `lang`, plus no routing guidance against the many sibling research tools, leaves gaps an agent would have to guess at.

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 only 50% — `lang` and `limit` carry no descriptions anywhere, and the description never explains them (e.g. does limit truncate the checklist?). The `file` and `codes` semantics are already fully documented in the schema, so the description adds essentially nothing for parameters despite the coverage gap.

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 concrete verb (audit) and resource (family tree / GEDCOM) and enumerates the exact classes of findings it produces (impossible facts, duplicates, gaps). No sibling tool performs auditing, so it is trivially distinguishable, and the 'to-do list for the next search' framing clarifies the output's purpose.

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 only implied: the 'to-do list for the next search' hint suggests running it before planning searches, but it never says when to prefer this over plan_research, find_sources, or where_are_records, nor any prerequisites. Adequate context, no explicit when/when-not 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 already establish read-only and closed-world behavior. The description adds that the result is a range with 'exact and loose' variants, but it does not define those variants, state assumptions, or explain calendar handling, so the added behavioral context is limited.

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 a single compact, front-loaded sentence with no filler. Although 'exact and loose' is cryptic, the overall structure is appropriate and every phrase contributes.

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 simple two-parameter calculation tool, annotations cover safety and an output schema exists for return values, so the description need not explain output. It still omits routing guidance versus sibling date tools and leaves 'exact and loose' input assumptions implicit, but it is effectively complete for basic invocation.

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 50%: record_date has a schema description, while age does not. The description clarifies that age comes from a historical record and lists example record types, but it does not specify age units, expected format, or how record_date affects the calculation.

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 the resource and computation clearly: a birth-year range implied by an age in a record, with concrete record contexts. It does not explicitly differentiate from sibling tools such as normalize_date or convert_calendar, so it is clear but lacks named sibling differentiation.

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 implies use when interpreting an age from a census, confession list, or death record, giving useful context. However, it provides no explicit when-not conditions and does not name alternative tools, so usage must be 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 already declare readOnlyHint=true and openWorldHint=false. The description adds real behavioral context beyond that: the fact-by-fact comparison method, name-variant handling, Julian calendar and rounded-age tolerance, and a full verdict taxonomy with a threshold for 'confirmed'. It omits nothing critical for a pure local computation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core question and a tight parenthetical on special handling, then the verdict list. No filler; every clause earns its place.

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

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

With an output schema present, the description need not explain return values, yet it helpfully enumerates verdicts anyway; annotations cover the safety profile. The remaining gap is the unexplained 'lang' and 'year_tolerance' semantics, which is minor for this comparison 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 50%: 'known' and 'found' are described, but 'lang' and 'year_tolerance' have no descriptions in the schema. The description hints at tolerance behavior (Julian/rounded-age) without mapping it to 'year_tolerance', and never explains what 'lang' controls. Adequate but not compensating for the coverage gap.

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 question ('Is the person in a found record ours?') that names the exact verb (compare fact by fact) and resources (known person vs. found record), then enumerates the output verdicts. This is clearly distinguishable from DNA-based siblings like dna_match and kinship.

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?

Implies the usage context (comparing a known person against a discovered record to decide if it is the right person) and gives useful decision criteria ('2+ independent facts beyond the name' = confirmed). However, it names no alternatives and states no when-not-to-use conditions, e.g. when to prefer dna_match.

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=false, so safety is covered. The description contributes real domain behavior (the century-dependent Julian drift: +10 in 1600s through +13 in 1900–1918), which is useful context beyond the annotations, but it says nothing about error handling, ambiguous-input resolution, or out-of-range dates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence that front-loads the core action and then parenthetically supplies the historical windows; every clause carries information. It is slightly over-packed but no sentence 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?

An output schema exists, so return-value documentation is not needed, and annotations cover the read-only/no-network profile. For a three-parameter read-only conversion tool, the description supplies enough domain framing, with only ambiguity/error behavior left unspecified.

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 67%, and the schema itself already documents the date string formats and explains that 'auto' recognizes Hebrew/Republican by month names. The description reinforces the calendar set and historical windows but adds little syntax or semantic detail for 'to' or 'from_calendar' beyond what the schema 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?

States a specific verb (convert) and resource (calendars) and enumerates exactly which calendars are supported, which is concrete and unambiguous. It does not, however, differentiate itself from siblings like normalize_date or feast_date, so the agent gets the 'what' but not the 'why not that one'.

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 only implied through domain context ('old records', the Julian windows before 1918 and Republican 1792–1805), which hints at genealogical date scenarios. There is no explicit when-to-use-vs-alternatives guidance relative to normalize_date or feast_date, so an agent must infer the boundary itself.

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=false, so the safety profile is covered and even the apparent 'writes a number' phrase is not a contradiction (it means emitting a numeral, not persisting). The description adds genuine behavioral context (the titlo-scan mode, the 11–19 units-first rule), but says nothing about error handling or ambiguous input.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with examples that earn their place by anchoring the numeral formats. Front-loaded with the domain context, though it is dense and the mode list could be split more cleanly.

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 tool with an output schema, the description supplies enough domain context (notation examples, the three operating modes) to invoke it correctly. The only real gap is how the tool disambiguates modes from a single free-form `value`.

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's own description already explains that `value` may be letters, a number, or a transcription. The description adds example formats and the 11–19 ordering note, which helps interpret inputs, but does not fully override the baseline since the schema does most of the work.

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 second sentence states three specific verbs (reads, writes, finds) applied to a named resource (Church Slavonic numerals / numerals marked with a titlo). This distinguishes it clearly from siblings like normalize_date or convert_calendar, which handle dates rather than numeral systems.

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 enumerates three modes but never says when to prefer this tool over alternatives or how the agent signals which mode it wants. Usage is implied by the input format rather than stated, so guidance is only minimal.

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, the description discloses an important behavioral fact: results are non-unique ('Several always fit'), so the output is a candidate set rather than a verdict. It also credits the underlying methodology (Shared cM Project 4.0 ranges). It doesn't say how many candidates come back, but the output schema presumably covers that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler. The core purpose is front-loaded and the disambiguation caveat follows immediately after.

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, single-required-input tool with an output schema present, the description supplies everything the agent needs: what the result means, its ordering, and that the result is inherently ambiguous. Return-value details are correctly left to the output 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 coverage is 50%: shared_cm is fully documented in the schema, while lang has only an enum and default with no prose. The description adds no parameter-level detail (no unit hints, no format/locale behavior), so it neither compensates for the gap nor goes beyond the schema. 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 description states a concrete transformation (shared DNA in cM → candidate relationships) and names the source of the ranges (Shared cM Project 4.0), plus the output ordering ('closest first'). It also distinguishes itself from a sibling by explicitly naming the 'kinship tool' as the complementary step rather than a substitute.

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 routing guidance: when several relationships fit, use documents and the kinship tool to disambiguate. What's missing is a positive trigger for when to reach for dna_match in the first place (e.g., vs. the kinship or check_match tools) — the agent must infer that this is the cM-interpretation step.

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=false, so the safety profile is known; the description adds genuinely new behavior — the output is a letter with deliberate [bracketed] placeholders and the tool never sends anything. That is exactly the kind of context annotations cannot express. It stops short of describing length, format, or what an incomplete draft looks like, but the key traits are covered.

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 with zero filler; the artifact is stated first, then the placeholder convention, then the crucial send-boundary note. Every sentence earns its place.

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

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

An output schema exists, so return shape needn't be explained, and the read-only annotation covers safety. What is missing given 17 mostly-undescribed inputs is guidance on which fields matter for which 'kind' (e.g. that zags wants born/died/place while repression wants person/details) — an agent can call the tool but cannot fill it well from the description alone.

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?

Seventeen parameters at only 24% schema description coverage, and the description offers almost nothing: aside from 'with what to attach' hinting at details, it never explains what 'what', 'details', 'project', 'archive', or 'years' should contain or how they interact. The heavy lifting falls on self-explanatory field names, which is not enough to compensate for the low coverage.

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: 'A draft letter to a registry office or an archive'. The description scopes the artifact (a letter with attachments, [bracketed] gaps) and the supported jurisdictions/languages, and explicitly states 'The user sends it — not the tool', which prevents the agent from misreading this as a send/dispatch tool. No sibling tool overlaps with drafting correspondence, so differentiation is implicit but effectively complete.

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 to reach for it (need a ready-to-send request letter for ZAGS, state, military or FSB archives, or an English/Spanish/Portuguese generic archive) and rules out the send step. It does not say what to do instead when no archive letter is needed, or which upstream tools (find_sources, where_are_records, plan_research) should precede 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 already declare this a safe read (readOnlyHint=true, openWorldHint=false), so the bar is low, and the description still adds real behavioral context: it produces a most likely year plus a save-ready explanation, and it cross-checks ages to flag probable namesake collisions (7 in 1850 vs 22 in 1882). It does not state how conflicts between relative-derived and age-derived estimates are resolved.

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 evidence heuristics, then the consistency-check behavior; only the parenthetical offset list is dense. Three sentences, each doing work, 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?

With an output schema present, return-value detail is correctly omitted, and the description still covers the estimation heuristics and the cross-validation behavior for a 9-parameter tool. Gaps are minor: no note on required vs optional inputs, defaults, or precedence when relative-based and age-based estimates disagree.

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 78%, so most parameters are documented in the schema itself; the description's value-add is explaining how those inputs combine (eldest child ≈ −27, spouse/siblings ±8, parents +18…+45, marriage ≈22) and that ages are also cross-checked. That is more than restating the schema, though the offsets largely duplicate the per-parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb+resource (estimate a birth year) and enumerates the evidence classes it consumes, so the agent knows exactly what kind of computation this tool performs. It does not, however, name or contrast itself with the close sibling birth_year_from_age, leaving the boundary between those two tools to 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?

Usage is implied rather than stated: the enumeration of relatives and record ages suggests 'use when you have collateral or documentary age evidence,' but there is no explicit when-to-use, when-not-to-use, or pointer to birth_year_from_age for the single-age case. Adequate but leaves routing 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and determinism are covered. The description adds genuine behavioral context beyond that: it computes both Julian and Gregorian dates and handles movable feasts derived from Easter, signaling non-trivial computation rather than a simple lookup. It does not, however, disclose ambiguity handling or whether both calendar results are returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both earning their place: the first front-loads the capability, the second motivates it with concrete, culturally specific examples. No filler or restatement of the name.

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

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

An output schema exists, so return-value semantics need not be explained, and the core concept plus feast examples are well covered. The remaining gap is the unaddressed influence of the 'church' parameter on movable feast dates, which an agent needs to call the tool correctly for Orthodox vs Catholic contexts.

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 only 33% — only the 'feast' parameter is documented, while 'year' and 'church' are bare. The description does not compensate: it never explains that 'church' (orthodox/catholic) materially shifts movable feast dates because Easter differs between the two, nor does it clarify the year format. With the schema leaving most parameters undocumented, the description needed to fill this gap and does not.

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 resource (the date of a church feast or fast for a given year) and specifies the computational scope — Julian and Gregorian calendars plus movable feasts counted from Easter. This clearly distinguishes it from siblings like normalize_date or convert_calendar, which deal with generic calendar conversion rather than feast lookup.

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 final sentence gives strong context for when the tool applies: records and family stories often date events by feast names, with vivid examples («родился на Покров», «венчались после Петрова поста»). It clarifies the motivating scenario but names no explicit alternative or exclusion (e.g., when to prefer normalize_date), leaving comparison 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?

Annotations already cover the safety profile (readOnlyHint, openWorldHint=false), and the description goes further by disclosing the plan's operating constraints: a request budget split into sessions, no parallel sessions, and a mandatory pause of at least an hour after HTTP 429, plus the thumbnail-vs-full-frame policy. These are concrete execution behaviours not present in the annotations. The rate-limit caveat describes guidance embedded in the plan output rather than the tool's own runtime behaviour, which slightly blurs the picture.

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 opening clause before the list of plan contents, and every element (order, thumbnails, budget, rate limit, logging) corresponds to something the agent must act on. It is dense and heavily parenthesised, bordering on a run-on, but there is little that could be cut without losing operational 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?

Because an output schema exists, the description is not obliged to enumerate return fields, and annotations cover the read-only nature. The description supplies the execution policy and logging target needed to use the plan correctly. The remaining gaps are the lang parameter and the absence of explicit routing away from the indexed-search siblings.

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 50%, so the description needs to compensate for the undocumented half. It touches parish, years, parts, and reading order conceptually, which overlaps with the schema text but adds no format or syntax detail beyond it, and it says nothing about lang. Baseline 3 is appropriate given partial schema coverage and no real semantic addition.

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 concrete resource and scope: a reading plan for unindexed FamilySearch films, per parish, years, and parts, with an explicit ordering and thumbnail strategy. The word 'unindexed' implicitly contrasts with the indexed-search siblings (search_online, find_sources), but no sibling is named as an alternative the way a 5 would require. An agent can still tell what it produces 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?

Usage context is implied by 'unindexed' (you use this when records aren't searchable) and by the downstream reference to project_coverage for logging what gets read. However, there is no explicit statement of when-not to use it, nor a named alternative such as plan_research or search_online. Guidance is inferable but not 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 already declare readOnlyHint=true and openWorldHint=false, so safety and closed-world behavior are covered. The description adds that this is a curated catalog of 171 sources where each entry carries 'what it holds and how to search it well', which is useful, but it says nothing about paging, result counts, or how the limit interacts with the catalog.

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 clause. The long geographic enumeration ('Caucasus and Central Asia, Eastern, Western and Northern Europe...') is somewhat padded since it essentially restates worldwide coverage already indicated by include_worldwide, but it does help an agent judge whether its region is covered.

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 8 parameters, an output schema, and annotations covering safety, the description need not explain return values. But it leaves the interaction of include_worldwide with country filtering and the meaning of limit/pagination unexplained, which matters for a tool with this many optional parameters.

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 63%, and the description only implicitly maps to the country, year range, and records parameters through its prose. It gives no added meaning for lang, text, limit, or include_worldwide, so the schema does most of the work and 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 description states a specific verb and resource ('Find genealogy databases and archives') and enumerates the filtering axes (country/region, period, kind of records). It is clearly distinct in spirit from siblings like source_details or search_online, but it never names an alternative to differentiate itself explicitly.

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 phrase 'for a country (or region), period and kind of records', so an agent can infer the right query shape. However, there is no statement of when to prefer this over where_are_records, source_details, or search_online, and no exclusions or prerequisites.

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=false, so the safety profile is covered and the bar is lower. The description usefully signals breadth of coverage (pre-1918 letters, archival citation forms), but adds nothing about behavior beyond domain examples, and an output schema already exists for return values.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence with the core purpose front-loaded and examples bracketed inline to show scope. No filler, though the fragment style (no explicit verb until the trailing 'explained') slightly strains readability.

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 zero-required-parameter read-only lookup with an output schema, the description covers scope adequately and need not explain return values. What it omits is the routing context: with 'kinship' among its siblings, an agent cannot tell from this text which tool to prefer for marriage-relation terms.

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 50%: 'term' is documented in the schema ('A word from an old document, or empty for all') while 'lang' carries only an en/ru enum with a default, which is largely self-explanatory. The description mentions no parameters at all, so it neither compensates for the coverage gap nor adds meaning 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?

The description names a specific resource (old Russian terms from archival records) and enumerates concrete coverage domains: estates, kinship by marriage, archive citation, administrative units, pre-1918 orthography. It is clearly distinguishable from most siblings, but it does not differentiate itself from the 'kinship' sibling, which covers overlapping marriage-relation vocabulary (шурин, деверь, золовка).

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 rather than stated: an agent can infer 'use this when a term from an old record is unfamiliar', but there is no explicit when/when-not and no routing to alternatives such as 'kinship' for relationship questions or 'record_guide' for document-type questions. Thematically scoped but no disambiguation.

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, openWorldHint=false), so the description only needs to add context. It discloses the output content (three-language terms plus DNA share), which is genuinely useful, but says nothing about determinism, error behavior for invalid paths, or how the optional inputs combine. Adequate but thin against a low annotation bar.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single well-formed sentence that front-loads the trilingual naming and ends with the DNA share. The parenthetical examples earn their place by showing the output format, though the description is dense and could be split for scannability.

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

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

An output schema exists, so return values need not be explained, and read-only annotations cover safety. However, with zero required parameters the description never clarifies that 'path' is an alternative to the up/down pair for specifying the same relationship, which is exactly the decision an agent must make 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?

The description contains zero parameter guidance—all five params (up, down, sex, half, path) are left to the schema, which only documents 60% of them. The 40% gap (sex enum values, the meaning of half) is unaddressed in either place, and the description's examples (троюродный брат, second cousin) illustrate output terms, not input syntax.

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 computation: naming what B is to A, in three languages, plus the expected DNA share. An agent can tell this is a kinship-term resolver distinct from siblings like dna_match or audit_tree. It stops short of 5 because 'What B is to A' is terse and the resource (relationship/kinship) is never named outright.

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?

There is no when-to-use, no prerequisite, and no named alternative (dna_match and check_match overlap conceptually but are never mentioned). Usage is only inferable from the genealogy context. Nothing tells the agent what input shape selects this tool versus the DNA-oriented siblings.

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

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

readOnlyHint=true and openWorldHint=false already establish that this is a safe, closed-world lookup, so the bar is lower. The description adds genuine behavioral context — that clerk/recognition distortions come back as hints and that look-alikes may be another family — but says nothing about determinism, interpretation confidence, or how the flagged second surname should be treated downstream.

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 statement is front-loaded and the parenthetical Soundex note is well placed, but the body is one dense run-on paragraph with long language and transliteration enumerations whose marginal value is low. It would read better split into what-it-does / variant classes / cautions rather than a single comma-chained block.

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 an output schema present, the description needn't explain return values, and all three parameters are documented in-schema at 100%. The description covers every variant class the tool produces, so an agent has enough to call it correctly; only workflow placement (when in a research sequence) 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%, so baseline is 3, and the description earns a step above it by clarifying what each kind actually produces: gendered surname pairs and transliterations for surnames, cross-language equivalents (Иван = Іоаннъ = Jan = Johann = Juan) for given names, and the Romanian/Russian renderings tied to the Moldovan origin. The 'auto' origin default is left to the schema, which is acceptable.

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 clause states a specific resource — 'all the forms a name can take in records' plus Daitch–Mokotoff Soundex codes — and the examples make the scope unambiguous (orthography, gendered forms, transliterations, cross-language given names). The verb is nominal rather than active ('all the forms...'), and no sibling is named, but the domain is distinct enough from kinship/check_match/glossary that an agent can place 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?

There is no explicit when-to-use, when-not-to-use, or alternative. Phrases like 'as hints' and 'look-alikes that are another family' implicitly signal caution in interpretation, but nothing tells the agent when to call this versus kinship, check_match or glossary, or whether it should be run before a record search.

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=false, so the safety profile is covered. The description adds the concrete behavioral contract of the transform (free-form input, ISO or GEDCOM output on either side of the arrow), but says nothing about unparseable input, ambiguous dates, error behavior, or whether output format is selectable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence with an arrow structure that front-loads the input contract and immediately follows with the output. No filler, no restatement of the tool name, and the parenthetical examples do real work.

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 an output schema present the description needn't explain return values, and with one parameter the surface area is small. What it covers — input variety and the two output standards — is the essential information; only edge-case behavior for invalid or ambiguous dates 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 0% and the schema only declares 'text' as a string, so the description must carry the semantic load — and it does, by demonstrating four distinct accepted input shapes: approximate qualifiers, ranges, Spanish month names, and dotted numeric notation. It still omits the full set of supported languages and formats, so it compensates well but not completely.

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 verb 'normalize' is implicit but unmistakable from the arrow mapping human-written dates to ISO/GEDCOM, and the concrete examples ('около 1899' → 'ABT 1899') make the resource and direction of transformation unambiguous. It does not, however, distinguish itself from plausible siblings such as convert_calendar or feast_date, leaving that routing work to the agent.

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?

There is no when-to-use, when-not-to-use, or alternative-naming guidance. The examples imply that messy, non-standard, or non-English date strings are the target input, but the agent gets no explicit rule for choosing this tool over convert_calendar or cyrillic_numerals.

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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-structured behavior: the output is always a hypothesis, must be saved as an open lead/'probably', and never written as a tree link, plus the warning about namesakes from other villages. It does not discuss limits, determinism, or what happens when candidates is empty.

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 opening clause, followed by the ranking factors, the caveat, and the settling record. The Петрович → Пётр / Ильич → Илья examples are short and directly illustrate the transformation, so every clause earns its place.

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

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

An output schema exists, so return values need no explanation, and the description covers the epistemic status, ranking logic and the null-candidates fallback (documented in the schema). For a nested-object analytical tool this is close to complete, though it omits when to prefer it over sibling analysis tools.

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 67% schema coverage and nested objects, the description still adds meaning: it explains that ranking runs on name, surname, village and age, and that godparents, sureties and the child's own children feed the evidence (a grandson named after him). That connects the narrative to the child/candidates fields rather than restating them.

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 transformation and output: deriving a father's given name from a patronymic and returning ranked candidates with arguments for and against, a namesake warning, and a settling record. That is far more specific than a tautology and lets an agent understand the tool's output shape. It never names or contrasts a sibling tool (e.g. check_match or kinship), so it falls short of the top band.

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 a clear usage rule for the result: "Always a hypothesis — save it as an open lead or 'probably', never as a link in the tree." That is strong guidance about how to treat the output. It does not, however, say when to reach for this tool versus the sibling analysis tools, so no alternatives are named.

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 true. The description usefully specifies the external target ('Sends the name to Wikidata') and flags partial coverage with 'with years where known' and 'where that attachment is known'. It does not add auth, rate-limit, or failure behavior, and the openWorld disclosure largely duplicates the annotation.

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 returned fields are front-loaded after the verb, which is good. However, the single em-dash-laden sentence is dense and back-loads the 'Sends the name to Wikidata' note, which could be stated as a short separate clause without the narrative phrasing.

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 an output schema present, the description needn't explain return values, and the read-only/open-world annotations cover the safety profile. The one real gap is that the lang parameter's meaning and defaults are never addressed, but otherwise an agent has enough to invoke 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?

Schema description coverage is 50%: the required name parameter is documented in the schema (with a precision example) while the lang enum has no description in either place. The description adds nothing about lang or about input format beyond what the schema already carries, so it neither compensates for the gap nor adds value.

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 gives a specific verb+resource (look a place up in Wikidata) and enumerates the returned fields — administrative units with years, coordinates, Wikipedia article, and church attachment. It never names or contrasts a sibling tool, but the purpose is unmistakable and distinct from the genealogy-utility siblings like name_variants or estimate_birth_year.

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 implies a usage context — 'a first step to the uezd, province and parish of a village' — so an agent can infer this belongs at the start of a place-research flow. It gives no explicit when-not condition and names no alternative tool, so guidance remains implicit.

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=false, so safety is covered. The description adds that output is an ordered plan with free/country-specific sources prioritized — useful behavioral context — but does not clarify whether the tool merely plans or also executes searches, which is a meaningful distinction given sibling tools that do search.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence with no filler, and the core deliverable is front-loaded. The trailing parenthetical about prioritization earns its place by encoding ordering policy.

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

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

An output schema exists, so return-value explanation is not required, and annotations cover the read-only profile. However, with seven optional parameters at 14% coverage, the description leaves an agent unclear on how country, period, and the free-text question interact when constructing a plan.

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 only 14% and the description only accounts for two of seven parameters ('country' and 'period'). It says nothing about the semantically important 'question' parameter (the only schema-documented one), nor about lead_id, project, or lang, so it does not compensate for the coverage gap.

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 artifact ('a step-by-step research plan') and enumerates what it contains — records, guides, sources, in order — which is clearly distinct from sibling tools like find_sources or record_guide that perform only one of those steps. It stops short of explicitly contrasting itself with those 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?

Usage is implied rather than stated: the phrase 'free and country-specific first' signals the ordering policy and hints this is the entry-point planning tool, but the description never says when to call it instead of find_sources or record_guide. No exclusions or prerequisites are given.

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 signal a non-read-only, non-idempotent operation, and the description usefully adds that data is persisted with the project and where (next to a .ged file, or in a server-side file for a gene-archive site). It stops short of describing error cases or exactly what 'mark' overwrites, but the storage disclosure is genuine value beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The front-loaded opening is good, but the long parenthetical about .ged files and gene-archive sites is dense and adds tangential storage detail, and the arrow notation is compressed. It is readable but not tight; several clauses could be trimmed.

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 an output schema present, return values need no explanation, and the description covers the data model, the three actions, and the persistence model for a 9-parameter mutation tool. An agent has enough to invoke it correctly, with only minor param-level gaps remaining.

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 arrow-chain data model (parish → year → part → film and frames → status) and the status vocabulary (complete, partial up to 'No. …', not found) reinforce and enrich the 'entries' parameter beyond the schema's own text. With 67% schema coverage this helps, though the somewhat non-standard 'lang', 'year_from', and 'year_to' params receive no description-side clarification.

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 conveys a specific domain resource (register-reading coverage: parish → year → part → film/frames → status) and reads clearly as a coverage-tracking tool. It does not, however, cleanly differentiate itself from nearby siblings like project_view, project_log, and project_save, so an agent must infer the boundary.

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 explicit workflow guidance: 'Mark each book when you finish it' and 'ask what is still unread ... before opening a film,' which maps onto the mark/unread actions. It stops short of naming alternatives or stating when NOT to use it (e.g., vs project_log or project_view).

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 bar is lower, and the description still adds real context: it distinguishes missing/broken references, missing locators, and reference presence, and warns that even a located citation needs inspection. That interpretive caveat is genuinely useful for an agent. It omits output shape and the meaning of ordering/limits, keeping it below 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?

Four sentences, front-loaded with the core action and scope, and the caveats each carry information an agent needs to interpret results. Some density in the third sentence, 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?

An output schema exists, so return values need not be described, and the description covers purpose, scope, and interpretation caveats well. However, with 0% parameter documentation it leaves limit and generations semantics dangling, which matters for a traversal tool with a default fan-out.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across four parameters, so the description must compensate and largely does not. It explains the role of project root and root_person_id and implies a generations cap ('up to 10'), but leaves limit and the generations default (4) unexplained, and the stated 10-generation cap is not tied to the parameter.

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: reviewing source references for birth/death/burial/residence/marriage events, in read-only mode. It is distinguishable from siblings like find_sources or project_coverage by its event-level evidence focus. It stops short of naming an alternative sibling explicitly, so it lands at 4 rather than 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 gives scope (project root or root_person_id, ancestors up to 10 generations, closer ones prioritized) but never states when to choose this over find_sources, source_details, or audit_tree. The exclusions ('does not verify parentage or change data') hint at boundaries without routing to alternatives, so usage 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?

Annotations already declare this is a non-destructive write that is not idempotent. The description adds real behavioral context beyond that: it is an append-style coordination log, negative results must be recorded, and the outcome semantics distinguish 'unavailable' from 'no hits.' It doesn't say what happens on duplicate entries, which is the main remaining gap for a non-idempotent write.

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, front-loaded with the core action and rationale, then the logging rule, then the parameter hint. No filler or redundancy.

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

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

With an output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies the workflow rationale and outcome semantics; only the unexplained 'scope' parameter and duplicate-write behavior keep it from being fully complete for a 7-parameter mutation 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 only 43%, so the description carries weight, and it does clarify usage of source_id/lead_id (checklist tracking) and outcome ('unavailable is not no hits' maps to the enum). However, the 'scope' parameter is left entirely unexplained in both schema and description, so compensation is incomplete.

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: 'Write a line in the project's research log.' The coordination rationale ('so nobody searches the same place twice') makes the intent unambiguous and distinguishes it from analysis/gathering siblings like plan_research or project_evidence, though no sibling is named explicitly.

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 conditions for use: log after a search, including negative results, and the caveat that 'unavailable is not no hits' tells the agent how to classify a failed lookup. No alternative tool is explicitly excluded or contrasted, which keeps it out of 5 territory.

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, the description discloses material behavior: dry_run defaults to true, saves happen within the owner's authorization, several policy keys and defaults are listed, and custom archive folders without site.json remain read-only with policy stored outside that folder. This is unusually rich operational context for a mutation 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?

The purpose is front-loaded, and the dense paragraph contains mostly useful operational details. It is somewhat cramped: defaults, key semantics, the read alternative, and the archive-folder caveat are packed into one block, reducing readability.

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

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

Given the output schema and annotations, the description covers the main call context: policy mutation, dry-run behavior, authorization, key defaults, and a read-alternative. It still omits important operational details like how existing policy is merged and what the project string should contain.

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 0% schema description coverage, the description does significant work by naming the expected changes keys and their defaults, including owner_tasks fields. It does not explain the project parameter's expected format or whether changes are partial merges, so it is strong but not fully compensating.

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 gives a specific verb and resource: 'Configure this project's policy only.' It also names project_view as the read-side alternative, so an agent can tell this is for policy mutation rather than general project viewing or saving.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly implies use when configuring project policy and explicitly routes reading of policy, resources and waiting questions to project_view what='workflow'. It lacks explicit when-not guidance or mention of other project-related siblings such as project_save, so it falls short of full 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?

Adds substantial behavior beyond the annotations: changes to existing records are logged with old/new value, reason and documents; in a site folder the write runs through `gene apply`, is refused on validation error, git-committed under the owner's name and triggers a rebuild; in a .ged only changed lines are rewritten and a backup copy is kept. That is exactly the write-side context an agent needs and cannot get from readOnlyHint/destructiveHint alone.

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 then branches into the two execution modes, so structure matches how an agent reasons about the call. It is dense but every clause carries operational meaning; only the site-folder `gene apply` sentence is heavy enough to slow scanning.

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?

Covers both target types, the logging/backup guarantees, and the human-in-the-loop requirement, and an output schema exists so return values need not be explained. What's missing is any note on the delete/field-removal path and on what happens when validation refuses the write (beyond 'refused if it adds an error').

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 71%, so the schema already carries most per-field detail (record shapes, dry_run, project paths). The description still adds meaning the schema does not: the ordering requirement to create the source first and then cite its S-id, and that the `reason` value is what lands in the corrections log. The `delete` flag is not discussed in the description at all.

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 ('Add or change a person, family, source or research lead in the project') and enumerates the record kinds, which maps directly to the `kind` enum. It is plainly distinguishable from read-oriented siblings such as project_view, project_log and project_evidence.

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 sequencing guidance ('Save the source first, then cite its S-id') and a consent rule ('Ask the user before writing into their archive or tree'). It lacks an explicit statement of when to prefer a sibling tool (e.g. project_transfer for moving data), so it falls short of a full when/when-not pair.

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 write (readOnlyHint=false), non-destructive, non-idempotent, closed-world behavior, so the safety profile is covered. The description adds genuinely useful behavior: the output format is GEDCOM 5.5.1 and the export lands next to the project file, and import creates a new project. It does not say whether import overwrites existing data or what permissions are needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence covering both operating modes with no filler. It is efficient, though the app-name parenthetical is slightly ornamental and the two modes could be split for faster scanning.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile. What remains missing for a 3-parameter mutation tool is the export-side meaning of 'file', any overwrite/merge caveat on import, and a pointer to project_save as the prerequisite — a real gap given the low 33% schema coverage.

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 33% (only 'file' is documented), so the description should compensate more than it does. It maps well onto the 'direction' enum by describing both export and import flows, and it hints at output location, but it says nothing about the required 'project' parameter and never clarifies the 'file' parameter's role on the export side.

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 pair with two named modes: exporting the project as GEDCOM 5.5.1 next to the project file, or starting a new project from an external GEDCOM. It also names target applications (MyHeritage, Ancestry, Gramps, Geni), which differentiates it from the project_view/project_save siblings. It falls short of 5 because it never explicitly ties these two modes to the 'direction' enum values.

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 two clauses imply when to use each mode (interop with other genealogy programs vs. onboarding a foreign GEDCOM), giving usable context. However, there is no explicit when-not-to-use, no required prerequisites (e.g. project must already exist/saved), and no mention of the project_save sibling it relates to.

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=false, so the safety profile is covered. The description adds real context by disclosing that the same read can target three quite different sources (a tracked research project, a gene-archive site folder, a .ged file), but it largely restates the what enum and says nothing about empty results, error behavior, or size limits on the tree checks.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences of reasonable length, with the session-start rule placed last so it is easy to miss. The opening sentence is a tangled em-dash chain with an embedded parenthetical list that is hard to parse on first read; the mode/return-value mapping would be far clearer as a short list.

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

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

An output schema exists, so return values need not be spelled out, and annotations handle the safety profile; the description covers source selection, the primary entry point, and most modes. The remaining gap is coverage of the 'workflow' and 'resources' modes and the 'lang' parameter, which leaves an agent guessing about two of seven behaviors.

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 60%, and the description compensates partially: it maps 'summary' to concrete contents (people, open leads, recent searches, problems) and 'record' to family and sources, which adds meaning beyond the enum. However it silently omits the 'workflow' and 'resources' enum values and never mentions the 'lang' parameter, so two documented gaps remain for a 5-parameter dispatcher.

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 (read) and enumerates what is read: project summary, a single record with family and sources, a text search, the search log, and tree checks. It is distinguishable from project_save and project_transfer, though it overlaps noticeably with the sibling project_log (it exposes a 'log' mode) without acknowledging that overlap.

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?

There is one explicit directive — "Start every session on an existing project with what='summary'" — which is genuinely useful. Beyond that, nothing tells the agent when to pick this tool over project_log, project_coverage, project_evidence, or audit_tree, nor when the record/search/checks modes are preferable to those siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the closed-world read profile is covered. The description adds genuinely useful behavior: an empty topic returns the list of guides, and it discloses the language coverage (full in en/ru/uk, partial elsewhere). It does not describe the response shape, but an output schema exists.

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 a single dense sentence with an em-dash clause; content is front-loaded with the guide's scope, but the long enumerated list and language tail make it heavier than needed and slightly 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?

With an output schema documenting returns and annotations covering safety, the description supplies the scope and topic vocabulary an agent needs. The main residual gap is explicit routing guidance relative to sibling research tools.

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, but the description earns more by giving natural-language topic names (parish registers, confession lists, repression files) that bridge to the enum values (metric_book, confession_list, repression), helping the agent map a user's wording to the correct enum. The lang fallback behavior is covered in the schema itself.

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 it is a guide covering how to read and find specific record types, listing concrete examples (parish registers, revision lists, WWI/WWII records, censuses, evidence evaluation). The intent is clear, but it does not distinguish itself from siblings like where_are_records or find_sources, and the phrasing 'a kind of record' is slightly awkward.

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 — consult this guide for record-type knowledge — and it notes that omitting the topic returns the list. However, it gives no explicit when-to-use versus where_are_records, find_sources, or glossary, leaving the agent to infer the boundary.

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 readOnlyHint and openWorldHint annotations: it discloses that the query is sent only to Gallica's documented ContentSearch API, that start is a zero-based offset, that access errors are incomplete checks rather than no hits, and that absence of an OCR hit does not prove absence from the scans. These are meaningful operational caveats an agent needs.

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 compact sentences with the core purpose and prerequisite front-loaded, followed by return-value and caveat details. No sentence is wasted, though the caveat cluster is slightly dense.

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 an output schema exists, the description need not explain return fields, but it still usefully clarifies that results are scan sequence numbers and stable page URLs rather than verified facts or printed page numbers. It also covers the main access-error caveat. The only gap is that limit behavior is not described.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains document_id's source and start's zero-based meaning, but leaves query and limit semantics to the bare schema titles with no added clarification.

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 OCR excerpts inside one Gallica book') and anchors the required document_id to its origin in search_online source='gallica'. This clearly distinguishes it from sibling tools that search across sources or retrieve metadata.

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 that document_id comes from search_online with source='gallica', giving clear context for when this tool applies. It does not name an explicit alternative tool to use instead when the book is not from Gallica, but the prerequisite 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 already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully adds that the output consists of links the user opens in a browser and enumerates the target sources, but it says nothing about the response shape beyond that (mitigated by the presence of an 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?

It is a single sentence that front-loads the core action ('Ready search links ... in the sources that take a search URL'), which is good. However, the long parenthetical source list with 'and others' adds length without much decision value for an agent.

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 an output schema present, return values need not be described, so the remaining burden is parameter and usage clarity. Given seven parameters at 14% schema coverage and no routing guidance against search_online, the definition is adequate but leaves meaningful gaps for correct invocation.

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 only 14%: of seven parameters, only 'variants' is documented in the schema. The description compensates partially by tying the tool to a name and its variants, but gives no meaning for place, country, year_from or year_to, which are the parameters most likely to be misused.

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 clear verb+resource: it produces ready-to-use search links for a name across named genealogy sources (FamilySearch, Internet Archive, Find a Grave, Arolsen, etc.). An agent can tell it generates links rather than performing a search. It does not differentiate itself from the sibling search_online, which is the main missed opportunity.

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 only implied: the tool is for building search links 'for a name, with the name's variants.' There is no explicit when-to-use vs. when-not guidance, and no reference to the likely-overlapping sibling search_online, so an agent must infer the distinction.

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 and external-call semantics are covered. The description adds genuinely new behavior: the call is live/one-site-only, it returns a defined record shape, and it should be repeated per name variant. It does not mention rate limits or what happens on a site failure/timeout, which is the remaining gap for a live external query 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?

Three short sentences, front-loaded with the action and return shape, then the enumeration rule, then the alternative-tool routing. No filler, though the parenthetical field list is slightly bulky and could have been dropped given the output schema exists.

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

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

An output schema exists, so return-value explanation is not required, and the annotations cover the safety profile. However, for a 9-parameter search tool with low schema coverage, key calling details (name field vs free-text query, date range, pagination offset) are missing from both description and schema titles, leaving the definition adequate but incomplete.

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 only 33% and the description compensates for very little: it never explains given/surname vs the free-text 'query' parameter, the year_from/year_to range, limit, place, or the Gallica-only offset semantics of 'start'. Only the source selection is hinted at ('that one site only'). For a 9-parameter tool with undocumented required/optional semantics, this leaves the agent to rely on sparse schema titles.

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 plus resource ('Search an open database live'), plus an explicit list of the returned fields (title, date, place, link, snippet) that tells the agent what it gets back without opening the output schema. It also names the scope boundary ('Sends the query to that one site only'), which separates it from multi-site or link-generation 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?

Explicit operational instruction ('Run it for each name form from name_variants') tells the agent how to loop this tool, and the exclusion clause names real alternatives ('for FamilySearch, Geneteka, Find a Grave and other sites without an open API use search_links'). Both when-to-use and when-not-to-use are stated rather than 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 already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered. The description adds that the result spans coverage, access and search tips, but says nothing about permissions, rate limits, or coverage gaps; an output schema exists so return-value detail isn't 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?

A single sentence with the resource scope front-loaded and the id-provenance hint in a compact parenthetical. Every clause earns its place.

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

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

With an output schema present, the return shape need not be described, and the description conveys what information the tool surfaces. The only real gap is the unaddressed lang parameter and the absence of any exclusion guidance against sibling guide tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the burden, and it only partially does: 'by id from find_sources' gives useful semantics for source_id. The 'lang' parameter (enum en/ru, default en) is never mentioned, leaving localization behavior undocumented.

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 resource and scope: 'Everything about one source from the catalogue', enumerating the content types (coverage, access, search tips). It implicitly separates itself from the lookup sibling find_sources by referring to it as the id provider, though it doesn't name an explicit contrasting alternative.

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 parenthetical '(by id from find_sources)' gives a clear prerequisite: you must run find_sources first to obtain the id. That is real routing guidance, but there is no statement of when-not to use it or which sibling to prefer for other record/catalogue questions.

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 establish readOnlyHint=true and openWorldHint=false (a safe, closed-domain lookup), so the bar is lower. The description nevertheless adds real behavioral context beyond them: that results are border-shift-aware rather than reflecting today's regions, that 1857–1878 southern Bessarabia is treated as Moldavian/Romanian, and that a village lacking its own church is reported via a neighbouring parish.

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 single dense paragraph is front-loaded with the core question and every clause carries content, but the heavy em-dash and parenthetical stacking (Bessarabia date spans, the church aside) makes it a run-on that is harder to parse than it needs to be. Content is not wasted, but structure is not earning its keep.

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

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

An output schema exists, so return-format details are rightly omitted, and the description covers both lookup directions, the year/village conditionals, and the border-change caveat for a genuinely complex domain. It is only missing fallback behavior for unrecognized or ambiguous place names.

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 75% and the description meaningfully extends it: it explains why 'year' matters (it decides country/county/archive when borders moved, with concrete Bessarabia spans), what 'village' yields (which church kept the registers, and how to find out), and gives accepted place forms ('Volhynia', 'Бессарабия', 'Cahul', «Измаильский уезд»). 'lang' is left to its enum, which is a minor gap.

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 resource and outcome: mapping a province/region (of the Russian Empire, Congress Poland, Galicia, Bukovina, East Prussia, the Baltics, the Caucasus) to the archives that hold its records, and notes it runs in both directions (modern region → historical provinces). The verb is framed as a question rather than a clean verb+resource, and it never distinguishes itself from the overlapping sibling place_history, so it stops 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?

Conditional usage is described for the optional inputs ('with a year, says whose land it was then'; 'with a village, which church kept its books'), which tells the agent when the extra parameters matter. However nothing states when to reach for this tool over place_history or record_guide, and there are no exclusions — usage is implied rather than directed.

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