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, and the description adds genuinely non-obvious behavior: output contains '[brackets]' gaps and the tool does NOT send the letter ('The user sends it — not the tool'). This boundary is exactly the kind of context annotations cannot convey.

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

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

Front-loaded and compact: purpose first, scope parenthetical, output caveat, and the crucial sending boundary packed into three short sentences with no filler. Slightly dense but nothing wasteful.

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

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

For a complex 16-parameter tool with low schema coverage, the description covers purpose and behavioral boundaries well and an output schema exists (so returns needn't be explained) — but the large set of vaguely-named inputs (what, place, years, details, relation) is left unexplained, leaving a meaningful gap 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 25% across 16 parameters, so the description would need to compensate, but it explains almost no parameters. Only 'kind' is meaningfully documented, and that lives in the schema, not the description. The '[brackets]' note hints at fill-in fields without mapping to any 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?

States a specific verb and deliverable: it drafts a letter to a registry office or archive, enumerating the archive kinds (ZAGS, state, military, FSB; English/Spanish/Portuguese). The agent can tell it produces a request letter rather than researching records, but the description does not explicitly differentiate it from near-domain siblings like record_guide or find_sources.

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

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

No explicit when-to-use/when-not guidance or named alternatives are given, so usage is only implied. The enumeration of archive kinds and the note about languages implicitly tells the agent the scenarios where it applies, but a caller must still infer it from the deliverable description alone.

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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered without description help. The description adds useful scope facts — 114 sources and the geographic coverage — plus that each entry carries 'what it holds and how to search it well', but says nothing about result shape, pagination, or how 'include_worldwide' changes behavior.

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: verb + resource first, then scope. It is efficient overall, though the long geographic enumeration (former USSR, Caucasus, Central Asia, Europe, Americas, Australia...) is the least value-dense portion.

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 owed, and the description covers purpose, filters and catalog breadth. It remains thin on when to prefer this over the related source/search siblings and on the semantics of include_worldwide and limit, leaving the agent to infer those.

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%, with descriptions for text, country and records but not for lang, limit, year_from/year_to, or include_worldwide. The description echoes the country/period/records axes but adds no syntax or format detail beyond what the schema already supplies, so it neither compensates nor regresses.

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' for a given country/region, period and record kind. This is clearly distinguishable from siblings like source_details (per-source detail) and where_are_records, though it never names a sibling to draw the line 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 named filter axes (country or region, period, kind of records), which tells the agent roughly when the tool applies. There is no explicit when-to-use-vs-alternative guidance, e.g. no rule for choosing find_sources over search_online or source_details.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by revealing that the tool computes Daitch–Mokotoff Soundex codes, pre-1918 orthography, male/female surname forms, and transliterations. However, it does not discuss limitations, determinism, or whether results are exhaustive.

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 front-loaded sentence with a colon-delimited list of examples. Every element earns its place by concretely expanding the scope of name forms. It is dense but not padded, though the long parenthetical list could be structured more scannably.

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 the description need not explain return values, and annotations cover the read-only nature. The description adequately conveys the generated content. However, it leaves clear gaps in parameter semantics and usage guidance for a tool with a non-obvious 'kind' parameter and many research-oriented 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?

With only 50% schema description coverage, the description needs to compensate, but it does not explain the 'name' parameter's expected format or how the 'kind' enum (surname, given, patronymic) changes the output. It gives examples of surname and given-name forms, but these are illustrative of output content rather than parameter semantics. The schema description for 'kind' is just 'What the name is', which the description does not clarify.

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

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

The description clearly states the resource — all forms a name can take in records, including Soundex codes, spelling variants, orthography, transliterations, and cross-language equivalents. It is not a tautology and gives concrete examples that make the tool's scope unmistakable. It stops short of a full 5 because it does not explicitly differentiate this tool from any sibling by name.

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 says what content the tool provides, but it never states when to use it, when not to use it, or which sibling tool to use instead. There is no guidance about prerequisites, appropriate contexts, or alternatives. An agent can infer some usage from the content list, but that is not explicit 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 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 declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds that the name is sent to Wikidata and that administrative-unit information includes years only where known, which usefully discloses both external transmission and incomplete data. It does not discuss rate limits, authentication, or failure behavior.

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

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

The description is two sentences, front-loaded with the core action and return values, then a short operational note. No sentence is wasted, and the key information comes first.

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 fully explained, though the description helpfully summarizes them. Annotations cover the safety and openness profile, but the unexplained lang parameter and lack of language-selection guidance remain gaps given the 50% 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 only 50%: the name parameter is well described in the schema, but the lang parameter has no description in either the schema or the tool description. The description only says 'Sends the name to Wikidata,' which repeats the obvious rather than explaining when to use en versus ru or what lang affects.

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: looking a place up in Wikidata. It further specifies the returned content — administrative units with years, coordinates, and Wikipedia article — and frames itself as a first step toward uezd, province, and parish. This is enough to distinguish it from the sibling research and genealogy tools.

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

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

The phrase 'a first step to the uezd, province and parish of a village' implies when the tool is useful in a research workflow. However, it does not state when not to use it or name alternatives among siblings. Usage is inferable but not explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe/closed-world profile is covered. The description adds the ordering heuristic (free and country-specific sources first), which is genuine behavioral context, but says nothing about auth needs, limits, or what the plan actually looks like.

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 that packs purpose, contents, and ordering heuristic without waste. Slightly dense but 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 annotations cover the safety profile. However, with five optional parameters and 20% schema coverage, the description leaves parameter usage under-documented, making it only minimally complete.

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

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

Schema description coverage is only 20% (just the 'question' param), so the description must compensate. It vaguely maps 'country and period' to country/year_from/year_to, but says nothing about lang or question and gives no format or default semantics beyond the schema.

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

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

The description names a clear resource (a step-by-step research plan) and enumerates what it produces: which records exist, which guides to read, which sources to search, in order. This meaningfully distinguishes it from lookup siblings like find_sources or where_are_records, though it never explicitly names those alternatives.

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: it signals this is the tool for sequencing a research effort ('in order', 'free and country-specific first'). There is no explicit when-to-use vs when-not-to-use guidance and no named alternatives, so the agent must infer the context.

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 a non-read-only, non-destructive, non-idempotent write, so the agent knows this mutates state. The description adds the append-style framing ('write a line') and the deduplication purpose, but does not disclose persistence behavior, whether entries can be edited or removed, or any permissions requirements.

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 short sentences with the core action front-loaded and the behavioral nudge ('Log negative results') placed last. No filler, though the phrasing is informal and omits any structural hints about required fields.

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. Still, the scope parameter is undocumented in both schema and description, and the tool's relationship to other project_* tools is unstated, leaving a mutation tool with meaningful gaps.

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 schema already documents action, result, and project in useful detail. The description reinforces the 'negative result counts' semantics for the result field but never mentions the undocumented scope parameter, so it does not compensate for the coverage gap. Baseline 3 applies.

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

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

States a specific verb+resource: 'Write a line in the project's research log', which clearly distinguishes it from siblings like project_view, project_save, and project_transfer. The added rationale ('so nobody searches the same place twice') clarifies intent but does not explicitly name a sibling to prefer instead.

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 instruction 'Log negative results' is genuine when-to-use guidance that most agents would otherwise miss. However, it never states when NOT to use this tool or how it relates to project_save/project_view for the same project data, leaving the boundary between logging and saving 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?

With annotations already declaring the non-read-only, non-destructive, non-idempotent profile, the description adds substantial extra context: every change is logged with old/new value, reason and documents; in a gene-archive folder the write is refused if it introduces an error, then committed to git under the owner's name and the site rebuilt; in a .ged file only changed lines are rewritten and a copy is kept. It does not explain the `delete` parameter or the degree of recoverability after a delete, which would complete the mutation 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 write intent is front-loaded in sentence one, and each subsequent sentence covers a distinct concern (logging, gene-archive path, .ged path, consent). It is dense and slightly long, but no sentence is filler; the two backends genuinely need separate treatment.

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 7-parameter mutation tool with nested objects and a helper output (gedcom_changes), the description covers the essentials: what is written, how it is logged, the two storage modes, safety refusal conditions, and the dry-run-to-preview workflow. Return values are covered by the output schema, so nothing critical 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 71%, and the description reinforces it rather than repeating it: it supplies the S-id citation workflow for `source_ids`, and the "save the source first" rule implies ordering semantics the schema cannot express. The `delete` boolean is left unexplained in the description, so it is not fully compensating for the uncovered 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 first sentence gives a precise verb+resource+scope: adding or changing a person, family, source or lead in the project, matching the schema's `kind` enum exactly. It is clearly separable from siblings like project_view, project_log and project_transfer, which read or move rather than write records.

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

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

It states a real prerequisite ordering ("Save the source first, then cite its S-id") and a consent rule ("Ask the user before writing into their archive or tree"), which tells the agent when to pause rather than call. It does not explicitly compare itself to any sibling tool or name a when-not-to-use case, so it stops short of the top band.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so credit goes to what the description adds: that the project persists 'between conversations', that the target may be a project, a site folder, or a .ged file, and what each mode returns ('one record with its family and sources'). No pagination or size caveats for the log, which is the main omission.

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

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

Purpose and source types lead, the mode list and the default-mode instruction follow — front-loaded and free of filler. The first sentence is long and packing an em-dash aside plus a colon list makes it denser than it needs to be, but nothing 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?

For a 5-parameter, multi-mode tool with an output schema (so return shape needn't be described), the description covers all three source types, all five modes, and the recommended entry mode. Remaining gaps are minor: no guidance on `lang`, and the empty-`project` listing behavior lives only in the 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 60% (id, query, project documented; lang and what are not). The description compensates heavily for `what` by expanding all five enum values and what each returns, and reinforces the id/query linkage. Only `lang` receives no explanation anywhere.

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 ('Read') plus resource (research project / gene-archive site folder / GEDCOM tree), and it enumerates the five modes matching the `what` enum, so the agent knows the surface area precisely. It falls short of 5 because it never distinguishes itself from siblings that sound overlapping (project_log for the log, audit_tree for 'tree checks'), leaving those boundaries to inference.

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

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

Gives one explicit when-to-use rule: 'Start every session on an existing project with what=summary' — a genuinely useful default. It does not state when to prefer search, log, or checks over each other, nor point to project_save/project_transfer for the write side, so guidance is clear but not exhaustive.

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?

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 the safety/live-network profile is partially covered. The description adds non-obvious behavior: the query is dispatched to a single site only, and it enumerates the returned fields, which goes beyond the structured data. It does not discuss rate limits or failure behavior, so it falls short of a 5.

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

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

Three tight sentences, front-loaded with the action and scope, then the routing rule. Listing the returned fields overlaps with the existing output schema, which is the only mild 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, leaving return values to the schema is acceptable, and the description covers the routing decision well. However, for a tool with five optional filters that are undocumented in both schema and description, the definition is still not fully complete for an agent trying to construct a query.

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 29% across seven parameters, so the description must compensate for given, surname, place, year_from and year_to, and it largely does not. The 'name_variants' sentence hints that name fields are run repeatedly, but no parameter's format, default, or interaction is clarified.

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

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

States a specific verb and resource ('Search an open database live'), names the return payload, and explicitly distinguishes itself from the sibling search_links for sites lacking an open API. An agent can pick between search_online and search_links without opening either schema.

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

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

Gives a concrete usage rule ('Run it for each name form from name_variants') and names the alternative plus the condition that selects it ('sites without an open API use search_links'). The one-site-per-call constraint is also stated, preventing misuse.

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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the border-shift caveat that the result is often not today's archive, and the reverse-lookup capability. It does not explain return shape, but an output schema exists, so that is acceptable.

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 opening sentence is long and wraps the core purpose inside a parenthetical list of record types and a geographic enumeration, delaying the verb-resource statement. The second sentence adds value but the whole is one dense block rather than front-loaded. It is not bloated, but structure could be tighter.

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 two parameters (one required, one enum), an output schema, and readOnly/openWorld annotations, the description supplies the missing domain context: the border-shift problem and bidirectional lookup. An agent can call this correctly. The only incompleteness is the undocumented lang parameter, which is minor.

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 exactly 50%: the place parameter is well documented with examples in the schema, but lang has only an enum and default with no description. The narrative in the description compensates partly by explaining what place can represent (province or region, historical or modern), which is meaningful, but the lang parameter remains undocumented in text. 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 specific function — mapping a place (historical province or modern region) to the archives that hold its records — and names the record types and the geographic scope, so the resource is clear. It does not, however, contrast itself with siblings like find_sources or place_history, which is the main thing keeping it out of the top score.

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

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

It gives a clear context for use — when you have a province or region and need to know which archive currently holds its records. The bidirectional note (historical province to archive, and modern region back to historical provinces) helps an agent decide the right input. No explicit when-not-to-use or named alternative, so it stops short of a 5.

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