pkinative-mcp

Overview Schema Source Related Servers Discussions Admin

Resolve OID (name, validate, list, encode, decode)

resolve_oid

Read-onlyIdempotent

Look up object identifiers: get registered names, validate X.660 syntax, list the registry, and encode or decode OIDs between dotted and hex forms.

Instructions

Object identifiers in one call. mode:'name' → the registered name of each dotted OID (null when unregistered; ≤ 1000 per call); 'validate' → X.660 validity of each (at least two arcs, first arc 0–2, second ≤ 39 under 0 and 1, no leading zeros — reported, never an error); 'list' → the engine's registry (oid, name, standard), filtered by a case-insensitive substring of the name or the OID, paged with offset / limit (default 200, ≤ 2000); 'encode' → the X.690 bytes of each OID as hex, form 'content' (base-128 content octets, default) or 'tlv' (tag + length + content), relative:true for a RELATIVE-OID (tlv only); 'decode' → the dotted OID of hex octets (content, or a whole TLV with form:'tlv') with its name. Refuses: a member outside its mode, relative without form:'tlv' (VALIDATION_ERROR); an invalid OID in encode (PKI_OID_INVALID — validate reports it instead); malformed octets in decode (PKI_OID_INVALID, PKI_ASN1_*). Token-frugal: verbosity:'summary', fields:[…].

Input Schema

Name	Required	Description	Default
`hex`	No	decode: the octets to decode (content octets, or the whole TLV with form:'tlv'). Hexadecimal (an 0x prefix, colons and spaces are tolerated).
`form`	No	encode / decode: 'content' (the base-128 content octets only) or 'tlv' (tag + length + content, i.e. the whole DER value).	content
`mode`	Yes	'name' (registered names), 'validate' (X.660 validity), 'list' (the registry, paged), 'encode' (dotted → hex), 'decode' (hex → dotted + name).
`oids`	No	name / validate / encode: the dotted OIDs (≤ 1000).
`input`	No	decode: the encoded OBJECT IDENTIFIER as a whole DER TLV (or any PEM block holding one): exactly one of pem / derBase64 / path. Exclusive with hex; implies form:'tlv'.
`limit`	No	list: page size (≤ 2000).
`fields`	No	Dot-paths to keep after verbosity (arrays map over elements); unmatched paths land in _meta.unmatchedFields.
`filter`	No	list: case-insensitive substring of the name or the dotted OID.
`limits`	No	Raise pkinative's 22 named security bounds for this call (trusted input only; absent keys keep the engine defaults). A value above an operator ceiling (PKINATIVE_MCP_MAX_INPUT_BYTES, PKINATIVE_MCP_MAX_KDF_ITERATIONS, PKINATIVE_MCP_MAX_PATHS_EXPLORED) is LIMIT_CEILING_EXCEEDED; describe_engine lists the defaults and the ceilings.
`offset`	No	list: first entry returned.
`strict`	No	Escalate the first engine warning to a PKI_STRICT_DIAGNOSTIC error instead of listing it in diagnostics[].
`pemMode`	No	'strict' (RFC 7468 exactly, default) or 'lax' (tolerates whitespace, line length and RFC 1421 headers).	strict
`relative`	No	encode / decode: a RELATIVE-OID (X.690 §8.20, universal tag 13) instead of an OBJECT IDENTIFIER — needs form:'tlv' (the engine encodes a relative OID as a whole TLV only).
`verbosity`	No	'summary' keeps the scalar fields only (token-frugal).	full
`encodingRules`	No	'der' (strict X.690 DER, default) or 'ber' (indefinite / non-minimal lengths and constructed strings, as legacy CMS producers write).	der

Output Schema

Name	Required	Description
`oid`	No	decode: the dotted OID.
`mode`	No
`name`	No	decode: the registered name (null when unregistered or relative).
`oids`	No	name: { oid, name\|null }; validate: { oid, valid }; encode: { oid, hex }.
`count`	No	Number of OIDs / entries in the result.
`limit`	No
`total`	No	list: entries matching the filter.
`offset`	No
`entries`	No	list: the page of registry entries.
`hasMore`	No
`allValid`	No	validate: true when every OID is valid.
`diagnostics`	No	Non-fatal concerns the engine raised (PKI_DIAG_*, de-duplicated, at most 200; explain_code explains one).
`diagnosticCount`	No
`diagnosticCounts`	No	Occurrences per diagnostic code.
`diagnosticsTruncated`	No	true when distinct diagnostics beyond the 200 listed were dropped.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 27, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: it names the refusal conditions and concrete error codes (VALIDATION_ERROR, PKI_OID_INVALID, PKI_ASN1_*), states that validate reports rather than errors, caps batches at 1000, and gives paging defaults. That is real behavioral context an agent cannot get from 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.

Conciseness4/5

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

Front-loaded with the mode map using a consistent mode:'x' → … pattern, followed by refusals and the token-frugal hint; nearly every clause carries information. It is a single very dense block with some restatement of schema enum values (form, mode), which costs a little scannability.

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

Completeness4/5

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

Rich annotations plus an output schema mean the description needn't explain return shapes, and it covers modes, errors and paging well. The notable gap against a 15-parameter tool is that the nested input object (pem/derBase64/path as an alternative decode source) and the limits/strict/pemMode knobs are never mentioned in the prose.

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

Parameters4/5

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 cross-parameter meaning: which parameters bind to which mode, the content-vs-TLV distinction, the ≤1000/≤2000 caps, the case-insensitive substring filter, and the rule that relative requires form:'tlv'. It stops short of mentioning the decode-via-input path (pem/derBase64/path).

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

Purpose5/5

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

Each of the five modes is given a specific input→output statement ('name' → registered name per OID, 'encode' → X.690 hex bytes, 'decode' → dotted OID plus name), so the agent knows exactly what the tool does in every branch. The OID-specific framing also implicitly separates it from the generic ASN.1 siblings.

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

Usage Guidelines4/5

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

The description routes within the tool ('an invalid OID in encode … validate reports it instead') and states the null-when-unregistered condition for 'name', which is genuine when-to-use guidance. It doesn't compare against siblings like decode_asn1 or encode_asn1, so the inter-tool choice is left implicit.

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