Skip to main content
Glama
toolkit-mcp-server

toolkit-mcp-server

by cyanheads

toolkit-mcp-server: hash value

toolkit_hash_value
Read-onlyIdempotent

Generate SHA-256/384/512 digests or HMACs and verify files, downloads, lockfile integrity entries, or webhook signatures against a supplied expected checksum.

Instructions

Generate a cryptographic digest or HMAC of a value, or verify a value against an expected digest. Set operation to "generate" for a digest, or "compare" to constant-time-check value against the expected digest — compare is timing-safe and avoids manual string equality checks. Omitting operation compares when expected is supplied and generates otherwise. Algorithm defaults to sha256; sha384 and sha512 are also secure, while md5 and sha1 are exposed ONLY for checksum and file-integrity compatibility and for verifying existing HMAC-SHA1 signatures, and must not be used for passwords, new signatures, or any other security purpose. Set secret to compute HMAC(algorithm, secret, value) instead of a plain digest, for generate and compare alike — the check behind webhook signatures such as GitHub's X-Hub-Signature-256 (pass the header value as expected) and HS256 JWT signatures; secretEncoding says how secret is written (utf8 default, hex, base64, or base64url for a JWK k), the result carries hmac: true, and the secret is never echoed back. digestEncoding selects the generated digest form: lowercase hex (default), base64, base64url (unpadded, the JWS signature form), or sri (-, the npm lockfile integrity and Subresource Integrity form, sha256/sha384/sha512 only, plain digests only). expected is recognized by its shape at the algorithm's digest length, so a published checksum can be pasted as-is: a bare hex, base64, or base64url digest; SRI, which may hold several space-separated entries as an npm integrity field can and matches when any entry for algorithm does; one checksum-file line as sha256sum, shasum, md5, or openssl dgst prints it ( , or SHA256 () = ); or a digest prefixed sha256: or sha256= (OCI and release-asset digests, webhook signature headers). A tag or prefix naming another algorithm fails rather than being ignored, a multi-line checksum file must be cut to the one line for the file, and with secret an SRI value or a tagged line fails, since both carry plain digests. inputEncoding controls how value is read before hashing (utf8 default, or hex/base64 for raw binary data) so binary blobs need no decode round-trip. The canonical use is matching a download against a vendor-published checksum or a lockfile integrity entry.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "value": "<value>"
    },
    "name": "toolkit_hash_value"
  }
}

Input Schema

NameRequiredDescriptionDefault
valueYesThe data to hash, interpreted per inputEncoding (raw text by default).
secretNoHMAC key. When non-empty, the digest is HMAC(algorithm, secret, value) instead of a plain hash, for generate and compare alike, so a compare then takes the HMAC itself as expected: an SRI value or a tagged checksum line carries a plain digest and is rejected. Read per secretEncoding and used exactly as sent, never trimmed; an empty string counts as absent. Never echoed in the result or in error messages.
expectedNoThe digest to compare against, recognized from its shape at the algorithm's digest length: hex (any case), standard base64, or base64url, bare or prefixed as <algorithm>:<digest> or <algorithm>=<digest>; SRI (<algorithm>-<base64>); or one checksum-file line, <hex> <file> (sha256sum, shasum, md5 -r) or SHA256 (<file>) = <digest> (BSD, --tag, openssl dgst). A string of only hex digits is always read as hex, and hex split by whitespace is rejected. A <hex> <file> line whose file name is only hex digits is read as a line only when <hex> has a supported digest's length (32, 40, 64, 96, or 128 characters) and neither the name nor <hex> plus the name, whitespace removed, has one; otherwise it reads as split hex and is rejected, as an md5 line for an 8-character name is (pass its bare digest, or put * before the name). An SRI value may carry several space-separated entries: entries for other algorithms are skipped, and it matches when any entry for algorithm matches. A tag or prefix naming another algorithm is rejected, as is a whole multi-line checksum file, and with a non-empty secret so are SRI and a tagged line, which carry plain digests. Supplying it with operation omitted runs a compare; it is rejected with operation "generate".
algorithmNoDigest algorithm. sha256 (default), sha384, or sha512 for security; md5/sha1 are for checksums and for verifying existing HMAC-SHA1 signatures only — not for new security use.sha256
operationNo"generate" produces a digest; "compare" constant-time-checks value against expected. When omitted, resolves to "compare" if expected is supplied and "generate" otherwise.
inputEncodingNoHow value is decoded before hashing: utf8 text, hex, or base64.utf8
digestEncodingNoForm of the generated digest: lowercase hex (default), standard base64, base64url (URL-safe alphabet, unpadded — the JWS signature form), or sri (<algorithm>-<base64>, sha256/sha384/sha512 only, and not with secret). Applies to operation "generate".hex
secretEncodingNoHow secret is written: utf8 text (default, as a webhook signing secret is), hex, base64, or base64url (as a JWK k member is). Read only when secret is non-empty.utf8

Output Schema

NameRequiredDescriptionDefault
hmacNoPresent (true) when the digest is an HMAC keyed by secret; absent for a plain digest.
errorNoPresent when the call failed. Absent on success.
digestNoDigest of value in the requested digestEncoding: lowercase hex, base64, unpadded base64url, or <algorithm>-<base64>; the HMAC when hmac is true. Present for operation "generate".
matchesNoConstant-time equality of the computed digest (the HMAC when hmac is true) against expected. Present for operation "compare".
algorithmNoThe algorithm used.
operationNoThe operation performed, after resolving an omitted operation.
lengthInBytesNoDigest size in bytes (32 for sha256, 48 for sha384, 64 for sha512, 20 for sha1, 16 for md5). Present for "generate".

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.4.1
    • changedInput schema / properties / expected / description
      Previous value: -"The digest to compare against, recognized from its shape at the algorithm's digest length: hex (any case), standard base64, or base64url, bare or prefixed as <algorithm>:<digest> or <algorithm>=<digest>; SRI (<algorithm>-<base64>); or one checksum-file line, <hex>  <file> (sha256sum, shasum, md5 -r) or SHA256 (<file>) = <digest> (BSD, --tag, openssl dgst). A string of only hex digits is always read as hex; hex split by whitespace is rejected, as is a <hex>  <file> line whose file name is only hex digits. An SRI value may carry several space-separated entries: entries for other algorithms are skipped, and it matches when any entry for algorithm matches. A tag or prefix naming another algorithm is rejected, as is a whole multi-line checksum file. Supplying it with operation omitted runs a compare; it is rejected with operation \"generate\"."New value: +"The digest to compare against, recognized from its shape at the algorithm's digest length: hex (any case), standard base64, or base64url, bare or prefixed as <algorithm>:<digest> or <algorithm>=<digest>; SRI (<algorithm>-<base64>); or one checksum-file line, <hex>  <file> (sha256sum, shasum, md5 -r) or SHA256 (<file>) = <digest> (BSD, --tag, openssl dgst). A string of only hex digits is always read as hex, and hex split by whitespace is rejected. A <hex>  <file> line whose file name is only hex digits is read as a line only when <hex> has a supported digest's length (32, 40, 64, 96, or 128 characters) and neither the name nor <hex> plus the name, whitespace removed, has one; otherwise it reads as split hex and is rejected, as an md5 line for an 8-character name is (pass its bare digest, or put * before the name). An SRI value may carry several space-separated entries: entries for other algorithms are skipped, and it matches when any entry for algorithm matches. A tag or prefix naming another algorithm is rejected, as is a whole multi-line checksum file, and with a non-empty secret so are SRI and a tagged line, which carry plain digests. Supplying it with operation omitted runs a compare; it is rejected with operation \"generate\"."
    • changedInput schema / properties / secret / description
      Previous value: -"HMAC key. When non-empty, the digest is HMAC(algorithm, secret, value) instead of a plain hash, for generate and compare alike. Read per secretEncoding and used exactly as sent, never trimmed; an empty string counts as absent. Never echoed in the result or in error messages."New value: +"HMAC key. When non-empty, the digest is HMAC(algorithm, secret, value) instead of a plain hash, for generate and compare alike, so a compare then takes the HMAC itself as expected: an SRI value or a tagged checksum line carries a plain digest and is rejected. Read per secretEncoding and used exactly as sent, never trimmed; an empty string counts as absent. Never echoed in the result or in error messages."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_expected`: operation is \"compare\" but no expected digest was supplied. `expected_without_compare`: operation is \"generate\" but an expected digest was also supplied, so it would be ignored. `expected_malformed`: expected is not a digest in any form the tool reads, spans several lines (a whole checksum file), or is an SRI value holding a token that is not an SRI entry. `expected_length_mismatch`: expected is a recognized digest form but its length does not match the algorithm, so compare would always fail. `expected_algorithm_mismatch`: expected names an algorithm other than the chosen one, in a checksum-line tag, an <algorithm>: or <algorithm>= prefix, or SRI entries none of which names the chosen algorithm. `sri_unsupported_algorithm`: digestEncoding is \"sri\" and algorithm is md5 or sha1, which SRI does not define. `invalid_input_encoding`: value is not valid for the declared inputEncoding (e.g. non-hex characters with inputEncoding \"hex\"). `invalid_secret_encoding`: secret is not valid for the declared secretEncoding (e.g. non-hex characters with secretEncoding \"hex\"). `sri_with_secret`: digestEncoding is \"sri\" on operation \"generate\" and a secret was supplied; SRI carries plain digests, not HMACs. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `missing_expected`: operation is \"compare\" but no expected digest was supplied. `expected_without_compare`: operation is \"generate\" but an expected digest was also supplied, so it would be ignored. `expected_malformed`: expected is not a digest in any form the tool reads, spans several lines (a whole checksum file), or is an SRI value holding a token that is not an SRI entry. `expected_length_mismatch`: expected is a recognized digest form but its length does not match the algorithm, so compare would always fail. `expected_algorithm_mismatch`: expected names an algorithm other than the chosen one, in a checksum-line tag, an <algorithm>: or <algorithm>= prefix, or SRI entries none of which names the chosen algorithm. `expected_plain_with_secret`: operation is \"compare\", a secret was supplied, and expected is an SRI value or a tagged checksum line (SHA256 (<file>) = <digest>), forms that carry plain digests, not HMACs. `sri_unsupported_algorithm`: digestEncoding is \"sri\" and algorithm is md5 or sha1, which SRI does not define. `invalid_input_encoding`: value is not valid for the declared inputEncoding (e.g. non-hex characters with inputEncoding \"hex\"). `invalid_secret_encoding`: secret is not valid for the declared secretEncoding (e.g. non-hex characters with secretEncoding \"hex\"). `sri_with_secret`: digestEncoding is \"sri\" on operation \"generate\" and a secret was supplied; SRI carries plain digests, not HMACs. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "missing_expected",
      -  "expected_without_compare",
      -  "expected_malformed",
      -  "expected_length_mismatch",
      -  "expected_algorithm_mismatch",
      -  "sri_unsupported_algorithm",
      -  "invalid_input_encoding",
      -  "invalid_secret_encoding",
      -  "sri_with_secret"
      -]New value: +[
      +  "missing_expected",
      +  "expected_without_compare",
      +  "expected_malformed",
      +  "expected_length_mismatch",
      +  "expected_algorithm_mismatch",
      +  "expected_plain_with_secret",
      +  "sri_unsupported_algorithm",
      +  "invalid_input_encoding",
      +  "invalid_secret_encoding",
      +  "sri_with_secret"
      +]
  2. Changed11 schema fields changedv2.4.0
    • changedInput schema / properties / algorithm / description
      Previous value: -"Digest algorithm. sha256 (default), sha384, or sha512 for security; md5/sha1 are checksum/compat only — not for security."New value: +"Digest algorithm. sha256 (default), sha384, or sha512 for security; md5/sha1 are for checksums and for verifying existing HMAC-SHA1 signatures only — not for new security use."
    • changedInput schema / properties / digestEncoding / description
      Previous value: -"Form of the generated digest: lowercase hex (default), standard base64, or sri (<algorithm>-<base64>, sha256/sha384/sha512 only). Applies to operation \"generate\"."New value: +"Form of the generated digest: lowercase hex (default), standard base64, base64url (URL-safe alphabet, unpadded — the JWS signature form), or sri (<algorithm>-<base64>, sha256/sha384/sha512 only, and not with secret). Applies to operation \"generate\"."
    • changedInput schema / properties / digestEncoding / enum
      Previous value: -[
      -  "hex",
      -  "base64",
      -  "sri"
      -]New value: +[
      +  "hex",
      +  "base64",
      +  "base64url",
      +  "sri"
      +]
    • changedInput schema / properties / expected / description
      Previous value: -"The digest to compare against, as hex (any case), standard base64, or SRI (<algorithm>-<base64>); the form is recognized from its shape at the algorithm's digest length, and a string of only hex digits is always read as hex. An SRI value may carry several space-separated entries: entries for other algorithms are skipped, and it matches when any entry for algorithm matches. Supplying it with operation omitted runs a compare; it is rejected with operation \"generate\"."New value: +"The digest to compare against, recognized from its shape at the algorithm's digest length: hex (any case), standard base64, or base64url, bare or prefixed as <algorithm>:<digest> or <algorithm>=<digest>; SRI (<algorithm>-<base64>); or one checksum-file line, <hex>  <file> (sha256sum, shasum, md5 -r) or SHA256 (<file>) = <digest> (BSD, --tag, openssl dgst). A string of only hex digits is always read as hex; hex split by whitespace is rejected, as is a <hex>  <file> line whose file name is only hex digits. An SRI value may carry several space-separated entries: entries for other algorithms are skipped, and it matches when any entry for algorithm matches. A tag or prefix naming another algorithm is rejected, as is a whole multi-line checksum file. Supplying it with operation omitted runs a compare; it is rejected with operation \"generate\"."
    • addedInput schema / properties / secret
      Added value: +{
      +  "description": "HMAC key. When non-empty, the digest is HMAC(algorithm, secret, value) instead of a plain hash, for generate and compare alike. Read per secretEncoding and used exactly as sent, never trimmed; an empty string counts as absent. Never echoed in the result or in error messages.",
      +  "type": "string"
      +}
    • addedInput schema / properties / secretEncoding
      Added value: +{
      +  "default": "utf8",
      +  "description": "How secret is written: utf8 text (default, as a webhook signing secret is), hex, base64, or base64url (as a JWK k member is). Read only when secret is non-empty.",
      +  "enum": [
      +    "utf8",
      +    "hex",
      +    "base64",
      +    "base64url"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / properties / digest / description
      Previous value: -"Digest of value in the requested digestEncoding: lowercase hex, base64, or <algorithm>-<base64>. Present for operation \"generate\"."New value: +"Digest of value in the requested digestEncoding: lowercase hex, base64, unpadded base64url, or <algorithm>-<base64>; the HMAC when hmac is true. Present for operation \"generate\"."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_expected`: operation is \"compare\" but no expected digest was supplied. `expected_without_compare`: operation is \"generate\" but an expected digest was also supplied, so it would be ignored. `expected_malformed`: expected is not a hex, standard base64, or sha256/sha384/sha512 SRI digest, or an SRI value holds a token that is not an SRI entry. `expected_length_mismatch`: expected is a recognized digest form but its length does not match the algorithm, so compare would always fail. `expected_algorithm_mismatch`: expected is SRI and none of its entries names the chosen algorithm. `sri_unsupported_algorithm`: digestEncoding is \"sri\" and algorithm is md5 or sha1, which SRI does not define. `invalid_input_encoding`: value is not valid for the declared inputEncoding (e.g. non-hex characters with inputEncoding \"hex\"). Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `missing_expected`: operation is \"compare\" but no expected digest was supplied. `expected_without_compare`: operation is \"generate\" but an expected digest was also supplied, so it would be ignored. `expected_malformed`: expected is not a digest in any form the tool reads, spans several lines (a whole checksum file), or is an SRI value holding a token that is not an SRI entry. `expected_length_mismatch`: expected is a recognized digest form but its length does not match the algorithm, so compare would always fail. `expected_algorithm_mismatch`: expected names an algorithm other than the chosen one, in a checksum-line tag, an <algorithm>: or <algorithm>= prefix, or SRI entries none of which names the chosen algorithm. `sri_unsupported_algorithm`: digestEncoding is \"sri\" and algorithm is md5 or sha1, which SRI does not define. `invalid_input_encoding`: value is not valid for the declared inputEncoding (e.g. non-hex characters with inputEncoding \"hex\"). `invalid_secret_encoding`: secret is not valid for the declared secretEncoding (e.g. non-hex characters with secretEncoding \"hex\"). `sri_with_secret`: digestEncoding is \"sri\" on operation \"generate\" and a secret was supplied; SRI carries plain digests, not HMACs. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "missing_expected",
      -  "expected_without_compare",
      -  "expected_malformed",
      -  "expected_length_mismatch",
      -  "expected_algorithm_mismatch",
      -  "sri_unsupported_algorithm",
      -  "invalid_input_encoding"
      -]New value: +[
      +  "missing_expected",
      +  "expected_without_compare",
      +  "expected_malformed",
      +  "expected_length_mismatch",
      +  "expected_algorithm_mismatch",
      +  "sri_unsupported_algorithm",
      +  "invalid_input_encoding",
      +  "invalid_secret_encoding",
      +  "sri_with_secret"
      +]
    • addedOutput schema / properties / hmac
      Added value: +{
      +  "const": true,
      +  "description": "Present (true) when the digest is an HMAC keyed by secret; absent for a plain digest.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / matches / description
      Previous value: -"Constant-time equality of the computed digest against expected. Present for operation \"compare\"."New value: +"Constant-time equality of the computed digest (the HMAC when hmac is true) against expected. Present for operation \"compare\"."
  3. Changed13 schema fields changedv2.3.1
    • changedInput schema / properties / algorithm / description
      Previous value: -"Digest algorithm. sha256 (default) or sha512 for security; md5/sha1 are checksum/compat only — not for security."New value: +"Digest algorithm. sha256 (default), sha384, or sha512 for security; md5/sha1 are checksum/compat only — not for security."
    • changedInput schema / properties / algorithm / enum
      Previous value: -[
      -  "sha256",
      -  "sha512",
      -  "sha1",
      -  "md5"
      -]New value: +[
      +  "sha256",
      +  "sha384",
      +  "sha512",
      +  "sha1",
      +  "md5"
      +]
    • addedInput schema / properties / digestEncoding
      Added value: +{
      +  "default": "hex",
      +  "description": "Form of the generated digest: lowercase hex (default), standard base64, or sri (<algorithm>-<base64>, sha256/sha384/sha512 only). Applies to operation \"generate\".",
      +  "enum": [
      +    "hex",
      +    "base64",
      +    "sri"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / expected / description
      Previous value: -"The expected lowercase-hex digest to compare against. Required when operation is \"compare\"."New value: +"The digest to compare against, as hex (any case), standard base64, or SRI (<algorithm>-<base64>); the form is recognized from its shape at the algorithm's digest length, and a string of only hex digits is always read as hex. An SRI value may carry several space-separated entries: entries for other algorithms are skipped, and it matches when any entry for algorithm matches. Supplying it with operation omitted runs a compare; it is rejected with operation \"generate\"."
    • changedInput schema / properties / inputEncoding / description
      Previous value: -"How value (and expected's pre-image, when relevant) is decoded before hashing: utf8 text, hex, or base64."New value: +"How value is decoded before hashing: utf8 text, hex, or base64."
    • removedInput schema / properties / operation / default
      Removed value: -"generate"
    • changedInput schema / properties / operation / description
      Previous value: -"\"generate\" produces a digest; \"compare\" constant-time-checks value against expected."New value: +"\"generate\" produces a digest; \"compare\" constant-time-checks value against expected. When omitted, resolves to \"compare\" if expected is supplied and \"generate\" otherwise."
    • changedOutput schema / properties / algorithm / enum
      Previous value: -[
      -  "sha256",
      -  "sha512",
      -  "sha1",
      -  "md5"
      -]New value: +[
      +  "sha256",
      +  "sha384",
      +  "sha512",
      +  "sha1",
      +  "md5"
      +]
    • changedOutput schema / properties / digest / description
      Previous value: -"Lowercase-hex digest of value. Present for operation \"generate\"."New value: +"Digest of value in the requested digestEncoding: lowercase hex, base64, or <algorithm>-<base64>. Present for operation \"generate\"."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_expected`: operation is \"compare\" but no expected digest was supplied. `expected_length_mismatch`: The expected digest length does not match the algorithm, so compare would always fail. `invalid_input_encoding`: value is not valid for the declared inputEncoding (e.g. non-hex characters with inputEncoding \"hex\"). Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `missing_expected`: operation is \"compare\" but no expected digest was supplied. `expected_without_compare`: operation is \"generate\" but an expected digest was also supplied, so it would be ignored. `expected_malformed`: expected is not a hex, standard base64, or sha256/sha384/sha512 SRI digest, or an SRI value holds a token that is not an SRI entry. `expected_length_mismatch`: expected is a recognized digest form but its length does not match the algorithm, so compare would always fail. `expected_algorithm_mismatch`: expected is SRI and none of its entries names the chosen algorithm. `sri_unsupported_algorithm`: digestEncoding is \"sri\" and algorithm is md5 or sha1, which SRI does not define. `invalid_input_encoding`: value is not valid for the declared inputEncoding (e.g. non-hex characters with inputEncoding \"hex\"). Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "missing_expected",
      -  "expected_length_mismatch",
      -  "invalid_input_encoding"
      -]New value: +[
      +  "missing_expected",
      +  "expected_without_compare",
      +  "expected_malformed",
      +  "expected_length_mismatch",
      +  "expected_algorithm_mismatch",
      +  "sri_unsupported_algorithm",
      +  "invalid_input_encoding"
      +]
    • changedOutput schema / properties / lengthInBytes / description
      Previous value: -"Digest size in bytes (32 for sha256, 64 for sha512, 20 for sha1, 16 for md5). Present for \"generate\"."New value: +"Digest size in bytes (32 for sha256, 48 for sha384, 64 for sha512, 20 for sha1, 16 for md5). Present for \"generate\"."
    • changedOutput schema / properties / operation / description
      Previous value: -"The operation performed."New value: +"The operation performed, after resolving an omitted operation."
  4. Changed6 schema fields changedv2.2.2
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "algorithm",
      +      "operation"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `missing_expected`: operation is \"compare\" but no expected digest was supplied. `expected_length_mismatch`: The expected digest length does not match the algorithm, so compare would always fail. `invalid_input_encoding`: value is not valid for the declared inputEncoding (e.g. non-hex characters with inputEncoding \"hex\"). Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "missing_expected",
      +            "expected_length_mismatch",
      +            "invalid_input_encoding"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "algorithm",
      -  "operation"
      -]
  5. Addedv2.0.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations cover the read-only/idempotent/closed-world profile, but the description adds substantially more: constant-time comparison semantics, that the secret is never echoed in results or errors, that the result carries hmac: true, and the precise failure cases (tagged checkums and SRI rejected with a secret, foreign-algorithm prefixes rejected, multi-line checksum files rejected). These are behavioral traits an agent could not infer from the schema or annotations.

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

Conciseness3/5

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

Purpose and operation routing are front-loaded, which is good, but the remaining text is a single dense block that re-explains expected-value parsing rules already enumerated in the schema description. The md5/sha1 warning and the checksum-line edge cases are repeated in both places, so not every sentence earns its place.

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?

For an 8-parameter tool with a rich schema and an output schema, the description covers the decision points an agent needs: operation defaulting, algorithm safety constraints, HMAC configuration, encoding choices, and the accepted forms of expected. Return-value details are left to the output schema, appropriately.

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 baseline is 3, but the description adds genuine cross-parameter meaning beyond the schema: how secret and expected interact (HMAC compare takes the HMAC as expected; SRI/tagged lines fail with a secret), why digestEncoding 'sri' is disallowed with secret, and concrete real-world referents for base64url (JWS) and sri (npm integrity/SRI). Some of the expected-shape rules are near-duplicated from the schema rather than added to it.

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?

The opening sentence gives a specific verb and resource — generate a cryptographic digest or HMAC, or verify a value against an expected digest — which is immediately distinguishable from the encode/id/generate siblings. The follow-on sentence clarifies the two operations, so an agent knows exactly what capability this tool exposes.

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?

Explicit routing logic is given: 'generate' for a digest, 'compare' for a timing-safe check, and the default resolution when operation is omitted. It also names the canonical use case ('matching a download against a vendor-published checksum or a lockfile integrity entry') and states when the weak algorithms are acceptable versus forbidden, which is the key when-to-use/when-not distinction here.

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