iana-registries-mcp-server

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

Annotations already establish the safe-read profile (readOnlyHint, idempotentHint, openWorldHint), but the description adds real behavior the annotations do not: sub-registry listing when none is specified, nested-table listing, field names being XML element names, and cursor-based paging for large registries.

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

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

The core purpose is front-loaded, but the body is a single dense paragraph carrying long parenthetical matching rules that duplicate the schema. Much of the middle is redundant with structured fields and could be trimmed without loss.

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 shape need not be explained. Given that, the description covers the remaining edge cases an agent needs: sub-registry listing, nested tables, pagination cursor reuse constraints, and the search sibling for id lookup.

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 100% and the value-matching prose in the description largely restates the schema's own text, including the digit/0x range semantics. The added value is mostly the worked examples, which do not go meaningfully beyond what the schema already documents, so the baseline 3 applies.

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

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

Opens with a specific verb+resource ("Read records from any IANA XML registry by id") and grounds it with concrete examples (tls-parameters, protocol-numbers, http-methods, cbor-tags). It is clearly distinguishable from the narrow iana_lookup_* siblings and explicitly hands off id discovery to iana_search_registries.

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 routes the agent to iana_search_registries for finding ids and explains the fallback behavior when no subregistry is given. However, with nine siblings in the namespace, it never states when to prefer a specialized tool such as iana_lookup_port or iana_lookup_media_type over this generic reader.

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 cover readOnly/idempotent/openWorld, so the description is freed to disclose what annotations cannot: per-call request budget (max 20 Datatracker requests), retry-inclusive accounting, exact per-id request costs, partial-failure semantics ('failed with reason request_limit'), and 'Unknown ids return found: false.' These are genuinely useful operational details. It stops short of 5 only because pagination/ordering of results across a batch isn't fully spelled out.

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 correctly with the core purpose, but the middle sentence is a run-on enumeration of accepted formats that could be trimmed, and the final sentence on request accounting is dense. It earns its length given the tool's complexity, but structure is somewhat heavy for a one-parameter 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?

Given a single parameter, full schema coverage, and an output schema, the description supplies the operational context an agent needs: batch limit, accepted input forms, partial-failure behavior, and per-type return shapes. It's complete enough to invoke correctly, with only minor gaps in cross-batch result ordering.

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. The description adds value by enumerating accepted identifier forms (bare number, 'RFC 9110', 'rfc9110', draft with/without revision, 'BCP 14', file name, URLs on specific hosts) and the 10-item batch cap, but this largely duplicates the schema's own item description. Marginal lift above baseline.

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 opens with a precise verb+resource+scope: 'Get the current status of up to 10 RFCs, Internet-Drafts, or BCP/STD/FYI series in one call.' This cleanly distinguishes it from sibling tools like iana_lookup_pen or iana_search_registries, which target different IANA resources. An agent can tell immediately this is the RFC/draft/series status tool.

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 rich input-format guidance (what strings are accepted) and explains the request-limit retry behavior ('failed with reason request_limit, to pass in another call'), which tells the agent when to re-invoke. It does not explicitly name sibling alternatives or state when NOT to use this tool, keeping it out of the 5 range.

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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds one genuinely useful behavioral note — that a miss means only that IANA has no entry, not that the header is invalid — but otherwise restates return content that the output schema already carries.

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 sentences, front-loaded with the purpose, then the argument constraint, then the caveat about misses. No filler and nothing that fails to earn its place.

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

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

With an output schema present, the description need not enumerate return fields, and the annotations cover safety. The mutual-exclusion constraint and the false-negative caveat are the two things an agent most needs, and both appear. Pagination mechanics are left entirely to the schema, which is acceptable but a minor gap.

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 100%, so name, keyword, status, limit, and offset are all documented in the schema, including the mutual-exclusion rule in each property. The description reinforces but does not extend that (case-insensitivity and keyword token matching are both already in the schema), so the baseline 3 applies.

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

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

States a specific verb and resource ("Look up a registered HTTP field (header or trailer) name") and names the exact identifier spaces it searches. It is clearly separable from siblings like iana_lookup_media_type or iana_lookup_http_status based on the resource alone.

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

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

Gives the key operational rule — "Pass exactly one of name or keyword" — and explains when keyword mode applies ("words matched against field names and comments"). It also warns that many widely used headers are unregistered, which guides result interpretation. No explicit routing against siblings such as iana_search_registries, 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 cover the safety profile (readOnly, idempotent, openWorld), so the bar is lower. The description still adds real behavior beyond them: the specific fields returned (phrase, class, reference with section, temporary/obsoleted/unused flags) and the important edge case that an unassigned code returns found: false with its unassigned range.

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 tightly packed sentences, front-loaded with the primary purpose, with zero filler. Every clause carries information: lookup mode, search mode, exclusivity constraint, and the return/edge-case behavior.

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

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

With an output schema present, the description need not enumerate return values, yet it still adds the useful unassigned-code edge case. The only gap is that it doesn't position itself relative to the many sibling lookup tools, which matters in a family of nine similarly named 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 100%, so all four parameters are already documented with ranges, defaults, and the mutual-exclusion note. The description restates the code/keyword exclusivity but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (look up / search) and resource (HTTP status code in the IANA registry), plus the secondary mode of searching reason phrases. An agent can distinguish it from iana_lookup_http_field or iana_get_rfc_status purely from the text.

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?

Explicitly states the code-vs-keyword selection rule ('Pass exactly one of'), which tells the agent how to invoke it correctly. It does not, however, contrast this tool against siblings like iana_search_registries or iana_lookup_http_field, so there is no explicit alternative routing.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the burden is light, and the description still adds substantive behavior: the tag is decomposed into language/extlang/script/region/variant/extension/private-use, deprecated subtags report their preferred value, and a canonical tag is returned. That is meaningful context 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?

Three dense sentences with the core action front-loaded and supporting behavior (canonicalization, deprecation, multi-type subtags) following in logical order. No padding, though the final subtag-type sentence is a niche 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?

An output schema exists, so return values need not be spelled out, yet the description still sketches the response (parts checked, preferred value for deprecated subtags, canonical tag, alternate types). Combined with a fully documented schema, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so all five parameters (including the subtag_type enum and limit/offset pagination) are already documented in the schema. The description restates the mutually exclusive tag/description rule and gives examples, but adds little syntax or unit information the schema lacks.

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 opens with a specific verb pair and resource: parse/validate a BCP 47 language tag against the IANA Language Subtag Registry, plus search subtags by description. This clearly separates it from the iana_lookup_http_field / lookup_media_type siblings, which address entirely different registries.

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

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

It states the mode-selection rule explicitly — pass exactly one of `tag` or `description` — and illustrates each mode with examples. It does not name a sibling as an alternative or state when-not-to-use, but for a self-contained dual-mode lookup that guidance is adequate.

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 readOnly/openWorld/idempotent, yet the description adds meaningful behavior: exact `type` lookups read the registration template and surface file-extension, intended-usage, and deprecated-alias statements, the template.available:false case, and replacement reporting for deprecated/obsoleted types. This is real context beyond the safety hints.

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

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

Front-loads the core purpose, then layers mode selection and return behavior in dense but purposeful sentences. No filler, though the paragraph grows long and could be broken for scannability.

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

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

For a five-parameter read tool with an output schema and full annotations, the description covers input modes, matching semantics, and edge cases (no template, deprecated types, unregistered 'x-' types). An agent has enough to call it correctly; only sibling routing is unaddressed.

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 100%, so the schema already documents every parameter including the enum, bounds, and mutual-exclusion rule. The description reinforces the type-vs-keyword choice but adds no syntax or format detail the schema lacks, so the baseline 3 applies.

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

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

States a specific verb ('Look up') and resource ('registered media (MIME) types'), so the agent immediately knows what the tool does. It does not, however, explicitly contrast itself with the sibling iana_lookup_* tools, relying on the resource noun alone for 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?

Clearly instructs to pass exactly one of `type` or `keyword`, explains keyword matching semantics (tokens against names/status annotations, never file extensions), and warns that unregistered 'x-' types are absent. It lacks explicit when-to-use-vs-sibling-alternative routing but covers the operational boundaries well.

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/openWorld, so the bar is lower. The description adds genuinely useful context beyond them: that arcs below the enterprise number are assigned by the enterprise (not IANA) and that contact details are not returned, preventing false expectations about output completeness.

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

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

Four sentences, front-loaded with the purpose and the parameter-selection rule, then the return value and two caveats. No redundant or filler text.

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, yet the description still succinctly notes what is returned and what is not (contact details). Combined with full schema coverage and clear annotations, an agent has everything needed to call this 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 100%, so the schema already documents all four parameters, including the pen number/OID forms and the limit/offset pagination. The description reinforces the mutually exclusive pen/organization rule but adds little format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb ('Look up') and resource ('Private Enterprise Number (PEN)'), and the name/title distinguish it cleanly from siblings like iana_lookup_port or iana_lookup_media_type. The description even clarifies the returned resource (organization and OID prefix).

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?

Explicitly says to pass exactly one of `pen` or `organization`, which is the key usage constraint. It lacks an explicit 'when not to use' or a pointer to an alternative sibling, but the either/or selection rule is clearly 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description goes further by disclosing output behavior: per-transport rows, range rows for unassigned ports, System/User/Dynamic classification bands, and DNS-SD names appearing without a port. It adds real context, though some of it overlaps the output schema.

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

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

Front-loaded with the core action, then the mode-selection rule, then result semantics and an edge case. Every sentence carries information an agent would otherwise have to infer; there is no filler.

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

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

An output schema exists so return values need not be re-explained, all six parameters are documented at 100% coverage, and the description supplies the one thing the schema cannot — how the three mutually exclusive modes behave and what the result set looks like. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the mutual-exclusivity rule and port bounds that each schema property already documents, adding little semantic meaning beyond the structured fields.

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 ('Look up IANA service name and transport protocol port assignments') and is instantly distinguishable from siblings covering other registries (HTTP status, media type, PEN, URI scheme, language tag). An agent can pick this tool without opening any schema.

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

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

Gives clear selection rules for the three lookup modes ('Pass exactly one of port, service, or keyword') and explains how keyword matches work. It does not, however, mention when to prefer this over the sibling iana_search_registries or state exclusions, so it stops short of a full 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, openWorldHint and idempotentHint, so the safety/idempotency profile is covered. The description adds little behavioral context beyond input normalization; it does not discuss pagination behavior or any other trait not already implied by the annotations and output schema.

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

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

Three compact, front-loaded sentences: purpose, invocation constraint, and return contents. Zero waste overall, though the closing 'Returns…' sentence partially duplicates what the output schema already documents.

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 full schema coverage, annotations, and an output schema, the description supplies enough to invoke the tool correctly (mode selection, normalization, return shape). Pagination via offset/next_offset is left entirely to the schema, a minor gap for a paginated lookup.

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 100%, so all five parameters are documented in the schema itself, including the ':'/'://' normalization and the scheme-or-keyword mutual exclusion. The description largely restates these facts and adds no meaning about limit, offset, or status beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource (look up a registered URI scheme), and the resource is distinct from every sibling (http field, http status, language tag, media type, pen, port, registry records). An agent can identify the right tool from the description alone without opening the schema.

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

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

Clearly specifies the two operating modes and the constraint 'Pass exactly one of `scheme` or `keyword`', with examples for each. It does not, however, contrast this tool with alternatives such as iana_search_registries, so no explicit when-not guidance is offered.

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, openWorldHint, and idempotentHint, so the safety profile is handled. The description adds that results include registration procedure and defining documents and that it covers the full IANA protocol registries index, which is useful behavioral context. However, it doesn't describe ranking beyond what the query schema already says, nor any limitations.

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 efficient sentences: purpose and examples first, then return values and registry coverage. No filler or repetition.

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 search tool with annotations covering safety and an output schema (though not shown in detail), the description provides enough – what it searches, examples, return contents, and scope. It could mention pagination via offset/limit, but that is already in the schema. Minor gap in not stating result ordering beyond what the query parameter already describes.

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 query, limit, and offset parameters are fully documented in the schema. The description just restates that it searches titles and categories, adding no extra syntax or format details beyond the schema.

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

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

States a specific verb (Find) and resource (IANA protocol registries and sub-registries) with matching scope (titles and protocol categories). It also names the downstream sibling iana_get_registry_records whose inputs it produces, clearly distinguishing it from the lookup_* tools that resolve specific values.

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

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

The description implies when to use it (to discover registries by keyword) and examples like 'tls cipher' show how to query. It mentions the relationship with iana_get_registry_records but doesn't explicitly say when not to use it or describe cases where a direct lookup tool would be better.

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