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

With no annotations, the description carries the full burden and does disclose a genuinely non-obvious behavioral trait: results are entity-scoped with nothing broken out per ADIF subdivision, a domain limitation an agent could not infer from the schema. It does not state error behavior or confirm the read-only nature, but the output schema covers the return shape.

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 short (two sentences) and every clause carries information, so there is little waste. The ordering is the problem: it leads with a mapping caveat before stating what the tool returns, which makes the first read harder than necessary.

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

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

For a 2-parameter lookup with full schema coverage and an output schema, the description supplies the one non-obvious semantic (entity-level granularity) plus sibling routing, which is most of what an agent needs. Minor gaps remain around the exact treatment of a supplied subdivision.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by signaling that per-subdivision output is meaningless here ('nothing per subdivision'), which tells an agent not to expect the subdivision parameter to shape results. It still does not say whether subdivision is rejected, ignored, or simply unused.

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 identifies the resource (DOK codes resolved against a DXCC entity) and explicitly distinguishes itself from the sibling darc_dok_search, which handles districts/towns. However, the leading clause 'DOK lists don't map to ADIF subdivisions' and the vague verb 'this answers' force the reader to reconstruct the actual purpose from the tool name rather than reading a clean verb+resource 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?

It names the alternative explicitly ('Use darc_dok_search for a district or town') and implies this tool is the entity-level path, which is a usable routing rule. It stops short of an explicit when-not/prerequisite statement (e.g. what happens if a caller does pass a subdivision), so it is clear context rather than full 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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing about read-only semantics, error behavior for invalid codes, or result completeness. It only lists output fields, which the output schema already covers.

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 that front-loads the DOK/special-DOK split and then lists the payload. It is efficient, though the colon-and-parenthetical construction reads more like schema notes than agent-facing guidance.

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-value enumeration is largely redundant, so the description's main remaining job is disambiguation and edge-case behavior — both of which are absent. For a simple one-param lookup this is adequate but thin.

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 single 'code' parameter is documented with examples in the schema itself, so the baseline is 3. The description restates the DOK/special-DOK distinction but adds no format, casing, or validation detail beyond what the schema already says.

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 implies retrieval of a single code's details by enumerating the returned fields ('district and local club', 'purpose, callsign, validity window and sponsoring club'), but never states a verb or explicitly says 'look up one DOK'. The word 'One' hints at single-record scope versus the plural siblings (darc_dok_search, darc_dok_codes_for), but no sibling is named or contrasted.

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 guidance, no statement of when this should be chosen over darc_dok_search or darc_dok_valid_on, and no mention of prerequisites or failure conditions for an unknown code. The agent must infer routing purely from the tool name.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the important matching rule (every word must appear, across multiple fields), but says nothing about case sensitivity, ordering/ranking of results, or what an empty result means.

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 sentence, front-loaded with the verb and resource, and every clause earns its place by defining the match semantics. Slightly terse for a domain-jargon tool, which costs it the top score.

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 excused, and the two parameters are fully documented in the schema. What is missing for a search tool is context on result ordering and how matches across different fields are prioritized or combined.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real param meaning by clarifying that 'text' is tokenized into words and that ALL words must match — an AND semantic the schema's 'Words to look for' does not convey.

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 (find) and resource (codes), plus the matching fields (name, prefixes, area wording, attributes). That scope is clear enough to separate it from lookup-style siblings, though no sibling is named explicitly and 'Darc Dok' domain jargon is never unpacked.

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 described AND-matching semantics imply a keyword-search use case, but there is no explicit when-to-use, when-not, or routing against alternatives such as darc_dok_lookup or darc_dok_codes_for. Usage is inferable rather than stated.

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?

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only inspection of list metadata (owner, edition, terms, file integrity hashes) but never explicitly states it's non-mutating, whether the call needs authorization, or whether results are cached or live. The SHA-256s hint at a verification/integrity use case, which is useful context, but for a zero-annotation tool this leaves meaningful gaps.

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 clause-packed sentence that front-loads the resource (the list) and its owner. No filler or repetition, though the dense clause list is slightly hard to parse on first read.

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 an output schema, so the description is not obligated to detail the return shape, and the fields it enumerates (owner, edition, terms, file URLs and SHA-256s) align with what an output schema would expose. What's missing is operation framing – the description reads as a list of fields rather than an action – and any sibling differentiation.

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 zero parameters there is nothing to document, so the baseline is 4. The description appropriately doesn't discuss inputs, which is correct 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?

Names the resource (a 'list' in the Darc Dok source) and enumerates specific data points: owner, served edition, terms, and owner's files' URLs and SHA-256s. This is more specific than a tautology, but it never names a verb or operation – is this a query? A fetch? – and it doesn't differentiate itself from siblings like darc_dok_lookup or get_version_info, which could plausibly return overlapping information.

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 when-to-use context and no comparison to alternatives. With five sibling tools, an agent has no signal for choosing this one without opening the schemas.

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 no annotations, the description carries the full burden and does disclose non-obvious behavior: special DOKs only count inside DARC's published window, and merged DOKs surface replaced_by (with the A49→A12 example). It omits auth/error behavior, but for a read-style validation query the edge-case semantics are the important part.

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 core question, followed by two edge-case clarifications that each earn their place. Slightly dense phrasing in the special-DOK clause but no filler.

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

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

For a two-parameter query with an output schema present, the description covers the semantics an agent needs and even foreshadows the replaced_by return field. Nothing essential is missing, though it could note what a false/invalid result implies.

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 both parameters are already documented with examples and formats; baseline 3 applies. The description adds only marginal value by reinforcing that 'code' may be a DOK or a special DOK, which the schema already 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 check ('Whether a DOK ... was valid on a date') with the resource and the temporal dimension, which distinguishes it from siblings like darc_dok_lookup or darc_dok_search that fetch rather than validate. It does not explicitly name those siblings, but the verb+resource is 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?

Usage is implied by the validity-check framing, so an agent can infer it wants this tool when the question is 'was code X valid on date Y'. There is no explicit when-to-use/when-not guidance and no pointer to alternatives such as darc_dok_lookup for plain code resolution.

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?

No annotations are supplied, but this is a zero-parameter, self-evidently side-effect-free read, so the burden is light. The description usefully clarifies what each returned value means (spec_version is the owner's edition), adding context beyond the field names, but says nothing about caching, freshness, or auth, and the output schema already enumerates the 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?

Two short sentences, purpose first and returns second, with no filler. Every clause carries information the agent can use.

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-arg version tool with an output schema, the description covers what an agent needs to select and call it. The only omission is a note on when in a workflow to call it, which is minor here.

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 no parameters, so by convention the baseline is 4. There is nothing for the description to compensate for.

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: retrieves the service's own version plus the edition of DARC's list it serves. That is clearly distinct in function from the lookup/search siblings, though the description never explicitly names them as alternatives. A reader knows exactly what this tool returns.

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 guidance is given. Version/edition checks are conventionally diagnostic, but the description does not say so, nor does it contrast with darc_dok_source_info, which sounds like it could cover related metadata. The agent must infer the trigger condition.

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