uuid_validate

Validate that a string is a well-formed UUID. Returns the detected version and variant without asserting any specific version.

To assert that a UUID must be a specific version, use the corresponding uuid_verify_v* tool instead.

Parameters

Parameter	Type	Required	Description
uuid	string	Yes	The UUID string to validate.

Response

Field	Type	Description
valid	boolean	true if the input is a well-formed UUID.
version	integer	UUID version number (e.g. 4 for v4, 7 for v7). Present when the UUID is structurally valid. null for invalid input.
variant	string	UUID variant string: "RFC4122", "Microsoft", "NCS", or "Future". Present when the UUID is structurally valid. null for invalid input.
error	string	Human-readable reason for failure. Only present when valid is false.

info

A malformed UUID is not an MCP error. It is returned as { "valid": false, "error": "..." } so agents can handle it programmatically without needing to catch exceptions.

Examples

Validate a well-formed UUID

{
	"uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Result:

{
	"valid": true,
	"version": 4,
	"variant": "RFC4122"
}

---

Validate an invalid string

{
	"uuid": "not-a-uuid"
}

Result:

{
	"valid": false,
	"error": "invalid UUID: invalid character: expected an optional prefix of `urn:uuid:` followed by [0-9a-fA-F-], found `n` at 1"
}

Errors

Each failure carries a precise code in the response. Argument-schema and server errors are JSON-RPC protocol errors; a rejected value is returned as a tool result with isError: true (so the agent can read the code and self-correct).

Code	When	Delivered as
invalid_arguments	The uuid argument is missing or the wrong type.	protocol error (invalid_params)
internal_error	An unexpected server error.	protocol error (internal_error)

Notes

• The parser accepts multiple UUID formats: standard hyphenated (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx), compact (no hyphens), and URN form (urn:uuid:...). Both uppercase and lowercase are accepted.
• Version detection reads bits 12–15 of the third UUID group as defined in RFC 9562. The nil UUID (00000000-0000-0000-0000-000000000000) parses as version 0.