Skip to main content
Glama

max_verify_signature

Read-onlyIdempotent

Verify MAX initData, requestContact phone hashes, or contact hashes locally and get clear reasons when signature checks fail due to wrong formulas, double decoding, or stale auth_date.

Instructions

Verify a MAX signature locally: mini-app initData (two-step HMAC), requestContact phone hash, or the hash of a contact shared through a request_contact button. Explains why a check failed (wrong formula, double decoding, stale auth_date). Available only when the server runs on your machine.

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": {
      "kind": "<kind>"
    },
    "name": "max_verify_signature"
  }
}

Input Schema

NameRequiredDescriptionDefault
hashNophone/contact: the hash to check
kindYesinit_data — mini-app launch data; phone — Bridge requestContact() result; contact — contact attachment from a request_contact button
langNoAnswer language: 'en' English, 'ru' Russian. Pick the user's language; default ru (or XONTA_MAX_LANG)
phoneNo
user_idNophone: MAX user id
vcf_infoNocontact: vcf_info exactly as received, JSON-decoded
auth_dateNophone: authDate from requestContact()
bot_tokenNoBot token; defaults to MAX_BOT_TOKEN from the environment
init_dataNoinit_data: raw window.WebApp.initData string
max_age_secondsNoinit_data freshness window

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false), so the description's added value is elsewhere: it discloses local-only availability and that the tool returns diagnostic explanations for failures (wrong formula, double decoding, stale auth_date). That is real behavioral information beyond the annotations, though it does not say whether verification output is a boolean, a reason code, or free text.

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?

Three tight sentences: purpose and variants first, failure diagnostics second, availability constraint last. Every clause carries information; the only minor redundancy is restating the three hash kinds that also appear in the schema's `kind` enum description.

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

Completeness3/5

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

For a ten-parameter tool with no output schema, the description should hint at the return shape; it only says failures are explained, not what success looks like. The parameter-grouping logic (which fields belong to phone vs contact vs init_data) is also left to the schema rather than summarized, leaving a meaningful gap given the tool's complexity.

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 90%, so the baseline is 3; the description earns a bump by explaining what is actually checked per kind — two-step HMAC for initData and freshness/staleness tied to auth_date, which gives the required `kind` and `max_age_seconds` context the schema alone does not. It still does not spell out which of the ten parameters are mandatory per kind.

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 and resource ("Verify a MAX signature locally") and immediately enumerates the three concrete verification paths: mini-app initData two-step HMAC, requestContact phone hash, and shared-contact hash. An agent can tell this apart from the mock/scaffold siblings (max_mock_init_data, max_bridge_mock) because the description frames it as checking an existing signature rather than producing one.

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?

Gives a clear gating condition — "Available only when the server runs on your machine" — which prevents an agent from calling it against a remote deployment. It also implicitly routes the agent across the three kinds. It does not name an alternative tool for crafting test data (e.g., a mock-init-data sibling), so the when-to-use-this-instead guidance is clear but incomplete.

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