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

Annotations already declare this read-only, idempotent, non-destructive and closed-world, so the safety profile is fully covered by structured data. The description contributes one real fact beyond that – the result unit is kilometres – but says nothing about invalid-locator handling 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?

A single front-loaded sentence with no filler; the unit is stated inline rather than tacked on. Nothing could be removed without losing information.

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

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

With an output schema present and annotations covering safety and idempotency, the remaining burden is small: the description need only characterize the inputs. It does that at a high level but omits locator format and error behavior, the two things an agent is most likely to get wrong.

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 parameters. 'Maidenhead locators' does establish the expected value type for both start and end, but it gives no format example (e.g. 'IO91wm'), no case or precision rules, and no way to tell which endpoint is which.

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 (calculates) and resource (distance between two points) plus the unit (km). It implicitly separates itself from calculate_heading by naming 'distance', but never mentions that sibling explicitly, so an agent must infer the split.

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 'use this when...' guidance, no exclusion of alternatives such as calculate_heading, and no statement of prerequisites. The only usable signal is the word 'distance', which requires 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 the safe, read-only, idempotent, non-destructive behavior. The description adds domain context about azimuth and Maidenhead locators, but does not explain direction convention, units, or edge cases.

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 with no filler; appropriately sized for a simple calculation tool.

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

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

The tool is simple and annotations plus output schema cover much of the context. However, the description leaves meaningful gaps around parameter format and start-to-end direction semantics.

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 indicates both inputs are Maidenhead locators, but does not specify locator format or clarify that heading is computed from start to end.

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: calculates heading/azimuth between Maidenhead locators. It is clearly distinct from calculate_distance by output type, though it does not explicitly reference that sibling.

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 the tool is for heading calculation between locators, but gives no explicit when-to-use guidance, prerequisites, or comparison to calculate_distance.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that both the server version and the spec version are returned, which is mildly useful context but nothing beyond the structured fields.

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

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

A single sentence with zero waste, front-loaded on what is returned. Nothing could be cut without losing meaning.

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 enumerate return fields, and the scope (server version + spec version) is stated. For a trivial zero-arg metadata tool this is complete; only minor informational gaps remain.

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

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

Zero parameters, so baseline is 4. The description does not need to explain any inputs, and correctly says nothing about them.

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

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

States a specific verb ('Returns') and resource ('version of the ADIF-MCP server and spec'). None of the siblings deal with versioning, so it is trivially distinguishable.

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 tool's scope — call it to learn server/spec versions — but there is no explicit when-to-use or when-not-to-use guidance. For a zero-arg, read-only metadata tool this is largely self-evident, so implied usage is adequate rather than exemplary.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so safety is covered. The description adds genuine value beyond that by explaining the semantics of the `source` field (ADIF's own export vs. derived by adif-mcp), which affects how a consumer should interpret results.

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, zero waste, with the core fact (26 enumerations, 25 + 1 derived) front-loaded before the interpretive note about `source`.

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

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

An output schema exists, so return values need not be spelled out here, and the description still clarifies the one field whose meaning is non-obvious (`source`). For a trivial no-arg list tool this is essentially complete; only the sibling contrast 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies for a parameterless tool.

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 ('Lists the 26 enumerations') and even quantifies the payload, noting 25 ADIF 3.1.7 enumerations plus a derived Country one. It does not explicitly contrast with the sibling `search_enumerations`, so an agent must infer that this is the exhaustive listing versus a filtered 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 phrase 'so a consumer loading reference tables can tell them apart' implies the load-everything use case, which softly distinguishes it from `search_enumerations`. However, there is no explicit when-to-use/when-not statement or pointer to the alternative.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The security note about reading local filesystem paths adds real context beyond the annotations, but behavior remains vague on what streaming means practically and what a parse result contains.

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

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

The purpose sentence is front-loaded and the security note is short enough to earn its place. Slightly more space is spent on the filesystem caveat than on the parameters an agent actually has to fill in.

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

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

With no output schema and 0% parameter coverage, the definition never explains what the parser returns (records, counts, boundaries) or how limit/start_at combine. For a paginated streaming parser, the agent lacks the information needed to call it correctly on the first try.

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 carries the full burden for limit, start_at, and file_path. "record seeking" loosely gestures at start_at and "large files" at limit, but neither the 1-based indexing, the default window size, nor the meaning of the path beyond the security caveat is explained.

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 ("Streaming parser ... ADIF files") plus a distinguishing trait (streaming, record seeking) that signals handling of large inputs. It does not differentiate from the sibling validate_adif_record, so an agent must infer parse vs. validate on its own.

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?

"for large ADIF files" is the only hint about when this tool is appropriate; there is no explicit when-to-use/when-not statement and no guidance on choosing between this and validate_adif_record or any other sibling. The choice is left entirely 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 read-only, idempotent, non-destructive behavior. The description adds genuinely useful context beyond that: unknown or unreadable names produce a tool execution error rather than a misleading error document, which tells the agent how failures surface.

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, purpose front-loaded, no filler. The second sentence is slightly elaborate in explaining the error-vs-error-document rationale, but it earns its keep by documenting a non-obvious failure mode.

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 annotations covering safety and an output schema covering return values, the description only needs to establish scope and failure behavior, which it does. The remaining gap is not pointing the agent to list_enumerations for discovering valid resource names.

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

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

Schema description coverage is 0% for the single parameter, so the description must carry the load. It supplies examples ('mode', 'fields', 'all') that add meaning beyond the bare string type, but it does not enumerate the valid set, leaving the agent to discover names elsewhere.

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: reads an ADIF 3.1.7 specification resource, with concrete examples ('mode', 'fields', 'all'). It does not explicitly distinguish itself from siblings like list_enumerations or search_enumerations, so it stops short of a 5.

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

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

Usage is implied by the examples of resource names, but there is no explicit guidance on when to use this versus list_enumerations or search_enumerations. An agent must infer the boundary from the names 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 readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds nothing about search semantics (substring vs exact, case sensitivity, which fields are searched) or the shape/nature of results despite having a search-based behavior worth disclosing.

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, front-loaded with the verb and resource, with no filler. Brevity is fine; the problem is missing content rather than excess.

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 isn't required, but for a search tool with an undocumented required parameter and 0% schema coverage, the description leaves an agent unable to construct a correct query or distinguish it from a sibling listing tool.

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

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

Schema description coverage is 0%, so the description must compensate and it largely does not. It loosely explains that 'enumeration' acts as an optional name filter, but the required 'search_term' parameter — the core of the tool — is never described at all.

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

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

States a specific verb and resource ('Searches ADIF 3.1.7 enumerations') and adds the version, but it never clarifies what is actually being matched or how it differs from the sibling list_enumerations, so an agent cannot confidently pick between the two.

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 when-to-use / when-not-to-use guidance and no mention of list_enumerations, the obvious alternative for enumeration browsing. The only hint is the word 'Optionally filter', which implies a search-first workflow but doesn't state it.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real context by naming the spec version 3.1.7 and that enum membership is part of the check, but it says nothing about what an invalid record yields (error vs. a result object) or whether validation is strict/lenient.

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 with no filler or repetition. It is efficient, though borderline under-specified rather than maximally informative.

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. However, for a validation tool the agent still needs to know the input shape it will accept and what a failed validation looks like; both are absent, leaving a gap for a single-parameter 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?

One parameter with 0% schema description coverage, so the description carries the burden. It only implies the parameter is an ADIF record string by naming it 'an ADIF record'; it does not clarify whether a header is required, whether multiple records are accepted, or expected formatting.

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 (validates) plus resource (ADIF record) plus the rule set version (3.1.7) and the enum-membership scope. This distinguishes it reasonably from parse_adif, though it does not explicitly state the relationship to that sibling or to list_enumerations.

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 statement of when to use this versus parse_adif, read_specification_resource, or list_enumerations. The agent must infer that this is the check-after-parse / pre-parse gate, with nothing in the text to confirm it.

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