Open Archives

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

Beyond the annotations (readOnly, non-destructive), the description discloses important behavioral traits: the order is fixed and cannot be overridden, results are always returned in full with no paging, and the hierarchical structure. These are not implied by annotations and add significant value for the agent.

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

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

The description is well-structured with a clear lead sentence, a reference to the mirrored URL, and a bullet-like list of the three modes. It is compact with no filler, and every sentence adds value. The front-loaded purpose and mode breakdown make it easy to scan.

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?

Despite having no output schema, the description provides essential context: what each mode returns (lists of archives, archive numbers, inventories), the ordering behavior, and the lack of paging. This sufficiently covers the tool's behavior for an agent to decide if it's the right tool, especially when combined with the readOnly/openWorld annotations.

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 explains the meaning and combination effects of archive_code and archive_number in detail, which is crucial given the schema description coverage is 0%. However, the 'lang' parameter is not mentioned in the description, though its enum values make it reasonably self-explanatory. The explanation of the other two parameters exceeds schema information.

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

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

The description clearly states the tool's function: 'Browse transcriptions hierarchically' with a specific verb and resource. It distinguishes itself from siblings by describing a hierarchical browse mode, and the three modes based on filters cover the full scope of behavior. The reference to the mirror URL and explicit mode descriptions makes the purpose unmistakable.

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 clearly indicates when to use the tool based on filters (no filter, archive_code, archive_code + archive_number), providing strong context for use. However, it does not explicitly state when NOT to use it or name alternatives like search_transcriptions for keyword searching, which would have made it a 5.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false. The description adds context about the returned array structure, specific fields (archive code, name, home URL, Twitter, ISIL, search URL), and a version note about ISIL codes and removed ArchiefWiki links, going beyond annotation-only information.

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, no filler. The first sentence front-loads the action, and the second sentence packs return-field details and a version note into a single efficient clause.

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

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

For a zero-parameter list endpoint, the description fully specifies the return payload and its use in other API calls. No output schema exists, but the description provides sufficient detail on the expected array to be self-contained.

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

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

The tool has zero parameters, so the description has no parameter semantics to add. The baseline of 4 is appropriate given the empty input schema and 100% schema 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?

The description clearly states 'List all archives with statistics', specifying the verb and resource. It further enumerates the exact fields returned, setting it apart from sibling tools focused on records, events, or statistics.

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 notes that the archive code is 'used in other API calls', signaling when to use this tool. However, it lacks explicit exclusions or direct references to alternative tools, though the niche purpose among siblings makes this minor.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is known. However, the description adds no behavioral context beyond the generic 'finds', such as pagination, result size limits, or how open-world search behaves.

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

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

The description is extremely concise with no wasted words, but it is under-specified for a tool with six parameters. Brevity is achieved at the expense of informative content, making it minimally acceptable.

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 six parameters, no output schema, and no enums, the description is grossly incomplete. It fails to convey return format, filtering semantics, or any operational detail, leaving the agent to guess from parameter names and annotations.

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 by explaining parameter meanings. It does not mention any of the six parameters, nor the required 'name' field, leaving the agent without semantic clues for correct invocation.

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 'Finds birth records' clearly states the action (finds) and the resource (birth records). It is unambiguous about what the tool does, though it does not explicitly distinguish it from sibling tools beyond the resource type.

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

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

The description provides no guidance on when to use this tool versus alternatives like search_records, browse_transcriptions, or get_deaths. It lacks context for selection criteria, prerequisites, or exclusions.

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 destructiveHint=false, so safety is covered. The description adds value by disclosing the version 1.1 change (archive_code replacing archive) and that results include archive name and record URL, which are behavioral details beyond the annotations.

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

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

The description is two front-loaded sentences with no fluff. The first states the core action, and the second provides return details and a version 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?

For a simple read-only tool with good annotations, the description covers purpose and return basics. However, it does not explain the 'number_show' parameter or mention pagination/record limits, leaving a gap for agents trying to use 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 0%, so the description must compensate. It clarifies 'years' as 'specified number of years ago', but completely omits explanation of 'number_show', leaving its meaning and constraints (max 100) undocumented in both schema and description.

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

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

The description clearly states the tool lists births a specified number of years ago, using a specific verb and resource. It distinguishes itself from the sibling get_births by focusing on the 'years ago' filter, and the version note adds further specificity.

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

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

The description implies usage for querying births exactly N years ago but does not explicitly compare with alternatives like get_births or state when not to use this tool. No explicit exclusions or alternative references are provided.

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 destructiveHint=false. The description adds valuable behavioral context such as the cap of 750 distinct groups, the inclusion of total record count, and the top-N groups based on sort. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose, followed by examples and response structure. Every sentence earns its place, with no fluff or repetition of schema details.

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 11 parameters and no output schema, the description explains the core filtering/grouping logic and the key response fields. It does not cover every parameter in depth, but it gives enough context for an agent to select and invoke the tool correctly for common use cases.

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%, so the description must compensate. It names the filter dimensions (archive, source type, event type, event place, year range) and lists group_by options, but leaves parameters like min_count, number_show, lang, and exact sort behavior only partially explained. The enums in the schema help fill some gaps.

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?

Description uses a specific verb ('Returns') and identifies the resource as record counts grouped by one chosen dimension, with concrete examples. It clearly communicates the tool's core function, though it does not explicitly differentiate it from sibling stats tools like get_record_stats or get_event_type_stats.

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

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

Provides explicit usage guidance: 'Use this endpoint to answer questions such as...' with examples like 'how many marriages per year in Amsterdam?'. It does not mention when not to use it or name alternative tools, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by explaining the nearest-year rounding behavior and listing valid census years. This behavioral insight is not redundant with the annotations.

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

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

The description is compact and front-loaded with the core purpose, followed by year details, sources, and input requirements. The data-source sentence is extra but not verbose; overall no wasted words.

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

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

The description provides a good overview but omits semantics for `province` and `richness`, and since there is no output schema, it also does not describe the response structure. This leaves gaps for an agent needing to understand what data will be returned or how richness affects results.

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

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

With 0% schema description coverage, the description compensates by clarifying that year is matched to the nearest available census year and that either place or gg_uri must be provided. However, it does not explain the `province` parameter or the `richness` enum (1,2,3), leaving these semantics 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?

The description clearly states 'Retrieves census data for a Dutch place or municipality for the census year nearest to the specified year,' which is a specific verb+resource pair. It distinguishes itself from sibling tools like get_births and get_deaths by focusing on census data, mentioning data sources and available years.

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 gives clear context for use (Dutch census data by place/year) and explicitly notes the input requirement that 'Either `place` or `gg_uri` must be provided.' However, it does not name alternative tools or state when not to use it, so it lacks explicit exclusions.

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 readOnlyHint and destructiveHint annotations, the description adds valuable behavioral context: it counts only 'validated' comments, states that no archive_code returns the global total, and includes a version note about parameter naming. This informs the agent about expected results and potential compatibility issues.

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 compact and front-loaded with the essential purpose, followed by two clear use-case scenarios and a version note. Every sentence adds value with no 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?

For a simple stats tool with one optional parameter, no output schema, and strong annotations, the description fully covers the tool's behavior. It explains the return value and the effect of the parameter, making it complete for an agent to invoke 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 schema provides no descriptions for archive_code (0% coverage), so the description carries the burden. It clearly explains the effect of providing or omitting archive_code, which compensates for the schema gap, though it does not specify the expected format or possible values for archive_code.

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

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

The description clearly states the tool's purpose: returning the total number of validated comments made on records. It specifies the distinct global and archive-specific modes, which differentiates it from sibling stat tools like get_record_stats or get_event_type_stats.

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

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

The description provides clear context on when to use the tool and how to use the optional archive_code parameter, explaining the two possible behaviors. It does not explicitly mention alternatives or when not to use, but the parameterized behavior is enough to guide an agent.

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 destructiveHint=false, indicating a safe read operation. The description adds no additional behavioral details, such as whether results are paginated or how search parameters affect outcomes, so it does not go beyond the annotations.

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

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

The description is short and to the point, with no extraneous words. However, it is under-specified and does not provide the substance needed for an AI agent to use the tool effectively.

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

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

Given the tool has five parameters and no output schema, the description should explain the input requirements and expected results. The one-sentence description omits all of this, making it inadequate 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?

The description does not mention any of the five parameters (name, start, eventyear, eventplace, number_show) or how they control the search. With 0% schema description coverage, the description completely fails to compensate for the lack of parameter documentation.

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 that the tool finds death records, which distinguishes it from sibling tools like get_births and get_marriages. However, it lacks any qualifiers about search scope or filters, making it a clear but minimal statement.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or search contexts. It simply states a generic action without contextual cues.

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 clarifies the filtering behavior and the version note about archive_code. It does not detail the exact output structure, but the behavior is sufficiently transparent.

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 concise, front-loaded, and each sentence adds value: a summary line, behavior with/without param, and a version note.

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 simplicity of the tool (one optional param, no output schema), the description covers the essential behavior. It could mention if results include counts only, but that is implied by 'record count statistics.'

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 fully explains the only parameter's semantic effect: absence returns global stats, presence filters by archive. It also notes the 1.1 naming convention, which is valuable context not in 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 clearly states it returns record count statistics per event type, with a specific verb and resource. The name and description distinguish it from sibling stats tools by specifying the dimension (event type).

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 provides clear context on how the optional archive_code parameter changes scope (all events vs archive-specific). However, it does not explicitly name alternative tools or provide when-not-to-use 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results are ordered by frequency and that Open Archives uses it for a visualization, but it does not discuss edge cases like zero results, pagination, or rate limits. With annotations covering safety, this is adequate but not rich.

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: a label and a concise functional statement. It is front-loaded and contains no filler or repetition of schema information.

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

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

For a read-only stats endpoint with 6 optional parameters and no output schema, the description gives a general overview but leaves parameter details and response structure to the schema, which has no descriptions. It explains what is returned (counts of family names) but not the result format, defaults, or how eventtype maps to event types. Acceptable for a simple tool but not fully 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 0%, so the description must compensate. It mentions place and period, roughly mapping to eventplace and eventyear range, but it does not explain eventtype enum values, lang, number_show, or the meaning of 'selected source types' (no such parameter exists in the schema). The description adds only vague conceptual mapping rather than specific parameter guidance.

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

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

The description clearly states the tool returns family name frequency statistics from events, limited by source types, place, and period, with results ordered by frequency. This specific verb+resource+scope distinguishes it from sibling tools like get_first_name_stats and get_profession_stats.

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 guidance on when to use this tool versus alternatives, or exclusions. The description implies its use case for family-name stats, but it does not mention sibling tools, prerequisites, or when other stats endpoints would be more appropriate.

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 read-only annotations, the description discloses an important behavioral rule: 'When a person has multiple forenames, only the first is counted.' It also discloses the current place limitation. These details add value beyond what annotations already provide.

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 purpose, followed by two essential clarifications. Every sentence adds value with no repetitive fluff.

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?

The tool is simple with three parameters and no output schema. The description covers what it returns, the counting rule, and the current place restriction. This is largely sufficient, though it could mention the year range or an example output for extra clarity, but those are not critical.

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

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

With 0% schema description coverage, the description carries more weight. It maps 'place' to the available value (Amsterdam), 'year' to eventyear, and 'top-X list' to number_show. This provides some meaning beyond the bare parameter names, but it does not thoroughly explain each parameter's semantics or constraints, leaving a gap that the schema alone does not fill.

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

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

The description states a clear verb and resource: 'Returns the top-X list of first names in the specified place and year.' It distinguishes from sibling tools by explicitly focusing on first names and mentioning that only the first forename is counted. This is specific and unambiguous.

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

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

The description implies usage for obtaining first-name statistics for a given place and year, and notes a restriction ('Currently only Amsterdam is available as a place'). However, it does not provide explicit guidance on when to use this tool versus alternatives like get_family_name_stats, nor does it state any exclusions.

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 provide readOnlyHint/openWorldHint. The description adds context about KNMI data sources, two time ranges, and warns that measurement types/units vary, which is useful beyond 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?

Two sentences, no filler, mentions key caveat about data variability. Could be slightly tighter but overall well-structured.

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?

The tool has 4 params, no output schema, and the description covers Dutch scope, source, and variability but leaves response shape and units unspecified. Given openWorldHint, it's adequate but not complete.

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

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

Schema coverage is 0%; the description references date and coordinates but doesn't define date format, coordinate system, or the lang parameter. It adds minimal semantic value beyond property names.

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 explicitly states it 'Returns historical weather measurements from the nearest Dutch weather station for the specified date and coordinates' — a specific verb+resource+scope that clearly distinguishes it from the sibling genealogy/transcription tools.

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

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

The description makes the use case clear: nearest Dutch station, historical dates, but no explicit comparison to alternatives or exclusions. Since siblings are obviously unrelated, a 4 is appropriate.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. However, the description adds only a minor scope clarification ('bride or groom') and does not disclose search behavior, pagination via start/number_show, or how matching works, leaving behavioral aspects unclear.

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 sentence with zero wasted words, front-loading the verb 'Finds' and resource 'marriage records'. It is appropriately sized for the minimal content it provides, earning high marks for efficiency.

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 6 parameters, 2 required, no output schema, and no parameter descriptions, this tool needs a richer description to be usable correctly. The current sentence omits essential details about required inputs, optional filters, and return values, making it far from 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 0%, so the description must compensate. It only loosely hints that name1/name2 may correspond to bride or groom, but does not define these fields explicitly, nor does it explain start, eventyear, eventplace, or number_show. This is inadequate given the absence of schema 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 clearly states the tool's function: 'Finds marriage records of couples (bride or groom)'. It uses a specific verb and resource, distinguishing it from get_births and get_deaths, though it could be more explicit about how it differs from general search tools like search_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?

The description provides no guidance on when to use this tool versus sibling alternatives such as search_records or browse_transcriptions. No exclusions or preferred usage scenarios are mentioned, leaving the agent without decision support.

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

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

Annotations already cover read-only (readOnlyHint), open world (openWorldHint), and non-destructive (destructiveHint) behavior. The description adds that results are 'ordered by frequency' and scoped by 'selected period and place,' which goes beyond the annotations. However, it does not disclose potential limits, defaults, or how missing parameters behave.

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 compact with three sentences. The first sentence ('Profession frequency statistics') is somewhat redundant with the tool name, but the second and third are useful. It is front-loaded with the core action and includes a relevant use case without unnecessary detail.

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?

The tool has 5 optional parameters and no output schema. The description provides the core behavior (frequency counts, ordering, period/place) but lacks parameter semantics for number_show and lang, and does not describe the response structure. It is adequate for basic understanding but not fully 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?

With 0% schema description coverage, the description must compensate, but it only clarifies 'selected period and place' (eventyearstart/eventyearend, eventplace). It leaves 'number_show' and 'lang' unexplained, leaving ambiguity for these parameters. This does not fully compensate for the schema 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 clearly states the specific action: 'Returns the number of times professions appear in records for the selected period and place.' It identifies the resource (professions) and the verb (returns), and distinguishes it from sibling stats tools by focusing on professions.

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

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

The description implies usage when profession frequency statistics are needed and mentions a concrete use case (Open Archives visualization), but it does not explicitly state when to use this tool over alternatives or provide exclusionary guidance. No sibling comparisons 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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses the conditional output behavior based on whether archive_code is provided. It also notes a version change in parameter naming, which is useful behavioral context.

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 concise and well-structured, starting with a clear one-line summary, followed by detailed behavior in two sentences, and a brief version note. Every sentence adds value with no redundancy.

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

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

Given the absence of an output schema, the description adequately explains what is returned in both modes and the effect of the optional parameter. The note about version 1.1 parameter naming is a thoughtful addition that prevents errors. No significant gaps are apparent.

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 input schema has no description coverage, but the description fully explains the single parameter archive_code: it is optional, and when provided, restricts results to that archive and changes the return structure. This adds significant meaning beyond the schema's bare type definition.

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

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

The description clearly states the tool returns record count statistics per archive, with specific behavior for when archive_code is present or absent. It is differentiated from sibling stats tools by focusing on record counts and archive/source-type granularity.

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 explains the two usage modes: omitting archive_code returns all archives, while specifying it returns source types for that archive. This provides clear context on how to use the tool, though it does not explicitly mention alternative tools or when not to use it.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description goes beyond that by explaining the filtering behavior based on archive_code and adding a version note about the parameter rename, providing useful behavioral context not present in annotations.

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

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

The description is concise, using only three sentences. It front-loads the core purpose immediately and every sentence adds value without redundancy.

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

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

For a simple one-optional-parameter read-only tool, the description covers all essential behavioral aspects: purpose, parameter effect, and versioning. It lacks explicit output format details, but the absence of an output schema and the presence of strong annotations make this acceptable.

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

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

The schema has only one parameter (archive_code) with zero description coverage. The description fully compensates by explaining exactly what happens without it (all source types) and with it (filtered by archive), plus a version note about the parameter name.

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 begins with 'Record count statistics per source type', which is a specific verb+resource combination. It clearly distinguishes this tool from sibling stats tools like get_event_type_stats and get_profession_stats by focusing on source types.

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 explains the behavior when archive_code is omitted versus provided, giving clear context for when to use each form. However, it does not explicitly name alternatives or state 'use this instead of X', so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds useful behavioral context: it searches by exact match criteria and returns specific URIs. No contradictions with annotations, and no mention of rate limits or auth, but the added detail about return content is valuable.

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, with the first providing a succinct summary and the second adding detail. It is front-loaded and contains no filler or redundant information.

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

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

For a simple 3-parameter tool with no output schema, the description adequately covers what the tool does and what it returns (Open Archives URIs). Gaps include handling multi-match cases and clarifying the 'lang' parameter, but overall the tool is sufficiently contextualized for an agent.

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 the 'name' and 'birthyear' parameters as search criteria, but does not explain the 'lang' parameter (enum nl/en). This partial explanation is helpful but leaves one parameter semantically undocumented, warranting a mid-range score.

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

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

The description clearly states the tool's purpose: matching a person to birth/death records by exact name and birth year, and returning Open Archives URIs. It specifies a precise verb ('match'/'searches') and resource ('genealogical dataset'), distinguishing it from sibling tools like generic search or record retrieval.

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

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

The description implies when to use the tool: when you have a person's exact name and birth year and want associated record URIs. However, it doesn't explicitly mention alternatives or exclusions, such as when to use search_records instead. The context is clear but lacks explicit 'when not to use' 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 cover readOnlyHint and destructiveHint, so the safety profile is known. The description adds that results are pageable and sortable and includes a version note about archive_code, which is useful, but it does not disclose return format details or other behavioral nuances beyond what annotations provide.

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 appropriately concise: two sentences plus a version note, with the main purpose stated up front. It contains no fluff or redundant elaboration beyond the slight restatement of the title, which is harmless.

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 12 parameters and no output schema, this description is incomplete. It vaguely promises 'found persons and records' but doesn't explain the result structure, pagination semantics, or the meaning of sort/start/number_show. It also fails to distinguish the tool from search_transcriptions, leaving a significant gap for an agent selecting among sibling 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%, and the description only lists some filter dimensions (archive, source type, event place, birth place, relation type, country) without explaining parameters like start, number_show, sort, not_archive, or lang. The mention of pageable/sortable is helpful but lacks specifics about offsets or sort enum values, so it only partially compensates 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 clearly states the tool searches genealogical records and returns found persons and records, listing supported filter dimensions. It uses a specific verb+resource and provides more detail than just the title, but it doesn't explicitly contrast with sibling tools like search_transcriptions, so it lacks direct 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?

The description gives no guidance on when to use this tool versus search_transcriptions or other search tools. There are no exclusions, alternatives, or context clues beyond the general 'Searches the genealogical dataset' phrase, leaving the agent to guess when this is the right choice.

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?

The description adds substantial behavioral detail beyond the annotations: results are fixed-ordered by Elasticsearch relevance, paginated, and each match includes a source citation, page identifier, and up to five highlighted fragments. It also discloses that facets depend on supplied filters, providing valuable context that annotations alone do not convey.

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

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

The description is three sentences long, front-loaded with the core purpose, and every sentence adds value: what it does, how it behaves, and what results look like. No redundant or fluff content.

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

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

Given the tool has 9 parameters and no output schema, the description covers the essential behavior (search, ordering, pagination, match contents, facets) but does not elaborate on pagination parameters (start, number_show) or filter specifics. It is sufficient for a search tool but leaves some 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?

With 0% schema coverage, the description must compensate by explaining parameter meanings, but it only vaguely refers to 'supplied filters' without detailing specific parameters like q, lang, start, number_show, year_start, or archive_code. The description does not add meaningful semantics beyond the parameter names themselves.

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

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

The description clearly states the tool performs a full-text search across page transcriptions, with a specific verb ('search') and resource ('page transcriptions'). It also distinguishes itself from siblings like search_records (which searches records) and show_transcription (which shows a single transcription), making its purpose unambiguous.

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

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

The description provides clear context by noting it mirrors the search UI at /transcripties/zoek.php and explains the search behavior. However, it does not explicitly state when not to use this tool or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context: JSON output with UTF-8 encoding, conformance to the A2A model, and availability of alternative formats (XML, GEDCOM, TTL, NT) by changing the file extension in the URL, plus version 1.1 improvements. This goes beyond what annotations provide.

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 four sentences with some redundancy ('Show a single' vs 'Returns one specific'). It is well-structured with a line break and includes essential format details, but could be slightly more concise by merging redundant statements.

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 read tool with no output schema, the description provides key information about response format, model, and alternative formats. However, it lacks parameter explanations and does not elaborate on the A2A model, so agents may need to infer details about archive/identifier. Overall, it is fairly complete for the tool's complexity.

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%, and the description does not explain the meaning of archive, identifier, or lang. The phrase 'single genealogical record' implies identifier/archive usage, but lang is entirely unmentioned. No parameter semantics are provided, leaving the agent to infer from the schema alone.

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 explicitly states 'Show a single genealogical record' and details the return format, distinguishing it from sibling tools like search_records or get_births by emphasizing a single specific record. The verb 'show' plus the resource 'single genealogical record' is specific and clear.

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 tool's purpose is clearly to fetch one record, which implies usage when a specific archive and identifier are known. However, it does not explicitly state when to prefer this tool over alternatives such as search_records or show_transcription, so it lacks clear exclusions or named alternatives.

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 as readOnly and non-destructive. The description adds valuable behavioral context beyond that: it specifies the exact content of the response (full transcript plus source citation) and deliberately states that AI-generated summaries are excluded. This helps the agent set expectations about the response scope without contradicting the annotations.

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

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

The description is just three sentences, front-loaded with the primary action ('Retrieve a single transcription'), then providing necessary detail about the return value and exclusions. Every sentence earns its place with 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?

For a simple read-only retrieval tool, the description covers the core behavior, the return payload, and an important exclusion. However, it omits any explanation of the 'lang' parameter and does not describe response format or error conditions. Given the annotations handle safety, the main gap is the undocumented parameter, making it mostly complete but not fully exhaustive.

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 input schema has 0% description coverage for its parameters, and the description does not explain them. While 'id' is inferable from the tool's purpose, the 'lang' parameter is completely undocumented—its meaning (e.g., language of the transcript or citation) is left ambiguous. The description fails to compensate for the schema's lack of parameter information.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Retrieve a single transcription.' It goes further to specify that it returns the full transcript along with a source citation, and explicitly notes that AI-generated summaries are not returned, which distinguishes it from sibling tools like view_transcription or search_transcriptions.

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

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

The description provides context that this is for retrieving a single transcription and mentions the endpoint it mirrors, but it does not explicitly state when to use this tool over alternatives such as view_transcription, nor does it give exclusions or prerequisites. The note about AI summaries implies an alternative but never names it, so usage guidance remains implied rather than explicit.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses significant behavioral traits: it opens an interactive viewer, shows transcription text alongside, supports optional highlighting, and falls back to a text summary plus inline preview images on hosts without MCP Apps support. This is rich, environment-dependent context not captured by annotations.

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

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

The description is three sentences, each earning its place: the first states the primary function, the second explains input format and provenance, the third covers optional highlight and fallback behavior. No redundancy or fluff.

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

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

For a read-only viewing tool with two well-documented parameters and no output schema, the description fully covers what the tool does, how to obtain valid inputs, what the user sees, and how it behaves in different host environments. It is self-sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by defining the exact identifier format ('<ISIL>_<archive>_<page>' with example) and stating that identifiers come from search_transcriptions / browse_transcriptions, which helps the agent construct valid input beyond the schema's generic 'array of strings'.

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 the specific action ('Open') and resource ('transcribed document pages in an interactive deep-zoom viewer'), and distinguishes from siblings by mentioning the deep-zoom context and the source of identifiers from search/browse. It also notes the optional highlight feature and fallback behavior, covering scope fully.

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 explicitly tells the agent to pass page identifiers returned by search_transcriptions / browse_transcriptions, giving clear workflow context and input provenance. It also describes the fallback for hosts without MCP Apps support, which helps set expectations. It lacks explicit 'when not to use' exclusions, but the context is strongly indicative.

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