pkinative-mcp

Overview Schema Source Related Servers Discussions Admin

Decode extension (one extnValue by OID, the 19 known kinds)

decode_extension

Read-onlyIdempotent

Decode one X.509 extension value by its OID into readable members, with criticality checks and malformed-value diagnostics. Pass extnValue DER as hex or base64 for full or summary output.

Instructions

Read-only decode of ONE X.509 extension value by its OID — the bytes INSIDE extnValue's OCTET STRING, as valueHex or value (DER by derBase64 / sandbox path) — exactly as inspect_certificate decodes a certificate's extensions: the 19 known kinds (basicConstraints, keyUsage, extendedKeyUsage, subjectAltName, nameConstraints, certificatePolicies, crlDistributionPoints, authorityInfoAccess, SCT list, …) come back with their members, any other OID as kind 'unknown' with its size; critical (default false) is reported and checked against the kind's RFC 5280 rule (a diagnostic, not a refusal). A value that is not well-formed for that OID is refused with PKI_X509_EXTENSION_MALFORMED (remedy: decode_asn1 for the plain tree). Token-frugal: verbosity:'summary', fields:[…]. The input is not a whole Extension SEQUENCE: pass the extnValue content, as inspect_certificate rawExtensions:true reports it in valueDer.

Input Schema

Name	Required	Description	Default
`oid`	Yes	The extension OID (2.5.29.19 basicConstraints, 2.5.29.17 subjectAltName, …) — it selects the decoder.
`value`	No	The extnValue content as DER bytes (derBase64, or a sandbox .der / .bin / .asn1 file): exactly one of pem / derBase64 / path. Exclusive with valueHex.
`fields`	No	Dot-paths to keep after verbosity (arrays map over elements); unmatched paths land in _meta.unmatchedFields.
`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.
`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
`critical`	No	The criticality to report and to check against the kind (a kind RFC 5280 requires critical or non-critical gets a diagnostic).
`valueHex`	No	The extnValue content (the DER inside the OCTET STRING) as hex. Exclusive with value. Hexadecimal (an 0x prefix, colons and spaces are tolerated).
`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
`kind`	No	One of the 19 decoded kinds, or unknown.
`name`	No	The registry name of the OID.
`decoded`	No	The decoded members of the kind (cA / pathLenConstraint, usages, purposes, names, keyIdentifier, …); empty for an unknown OID.
`critical`	No
`sizeBytes`	No	Size of the value DER.
`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.6/5.0

Behavior4/5

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds real context beyond that: unknown OIDs return kind 'unknown' with size, criticality is checked against RFC 5280 but is only a diagnostic (not a refusal), malformed values yield PKI_X509_EXTENSION_MALFORMED, and verbosity:'summary'/fields give token-frugal output. It stops short of describing pagination/response shape, which the output schema covers.

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?

The key distinction (what bytes to pass) is front-loaded and every sentence carries information. It is dense—long em-dash clauses with a lot packed into two sentences—which costs some readability, but nothing is filler.

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

Completeness5/5

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

Given 10 parameters, nested value object, an output schema, and 22 security bounds delegated to the schema, the description covers the one pitfall that causes wrong calls (whole Extension SEQUENCE vs extnValue content) and the failure/remedy path. Nothing an agent needs to invoke it correctly is missing.

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 description coverage is 100%, so baseline is 3; the description adds meaning on top by clarifying that value/valueHex must carry the extnValue content rather than a full Extension SEQUENCE, that valueHex and value are exclusive, and that critical defaults to false and is diagnostic only. That is genuine semantic value beyond the schema text.

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?

States a specific verb (decode), a precise resource (ONE X.509 extension value, the bytes inside extnValue's OCTET STRING), and scope via OID selection. It explicitly aligns itself with inspect_certificate's extension decoding and separates 'unknown' OID handling, so the agent can distinguish it from decode_asn1 and inspect_certificate without opening schemas.

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

Usage Guidelines5/5

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

Names the critical precondition ('The input is not a whole Extension SEQUENCE: pass the extnValue content, as inspect_certificate rawExtensions:true reports it in valueDer') and the alternative for malformed values ('remedy: decode_asn1 for the plain tree'). Both when-to-use and when-to-switch are explicit.

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