InsumerAPI

Overview Schema Source Related Servers Discussions Admin

Verify domain ownership

insumer_verify_domain

Idempotent

Check a merchant's previously requested domain verification token. The server looks for it as a DNS TXT record, HTML meta tag, or uploaded file, and marks the domain verified when found. Rate limited per merchant (429 says when to retry).

Instructions

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	Yes	Merchant ID

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	No	true when the API call succeeded
`data`	No	The endpoint's payload: a signed attestation, trust profile, discount, merchant or token records
`keys`	No	JWKS entries (insumer_jwks)
`meta`	No	Response metadata such as version and timestamp
`error`	No	Error details when ok is false
`items`	No	The result when the endpoint returns a JSON array
`message`	No	A plain-text result (insumer_setup), or a message from the API

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.16.0Oct 4, 2026

addedInput schema / properties / id / maxLength
```
Added value: +100
```
addedInput schema / properties / id / minLength
```
Added value: +1
```
addedInput schema / properties / id / pattern
```
Added value: +"^[a-zA-Z0-9_-]+$"
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "data": {
+      "description": "The endpoint's payload: a signed attestation, trust profile, discount, merchant or token records"
+    },
+    "error": {
+      "description": "Error details when ok is false"
+    },
+    "items": {
+      "description": "The result when the endpoint returns a JSON array",
+      "items": {},
+      "type": "array"
+    },
+    "keys": {
+      "description": "JWKS entries (insumer_jwks)",
+      "items": {},
+      "type": "array"
+    },
+    "message": {
+      "description": "A plain-text result (insumer_setup), or a message from the API"
+    },
+    "meta": {
+      "description": "Response metadata such as version and timestamp"
+    },
+    "ok": {
+      "description": "true when the API call succeeded",
+      "type": "boolean"
+    }
+  },
+  "type": "object"
+}

Addedv0.1.0Apr 28, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare the mutation/idempotency/open-world profile, and the description adds real context beyond them: the three lookup mechanisms (DNS TXT, HTML meta tag, uploaded file), the state transition ('marks the domain verified when found'), per-merchant rate limiting with 429 retry semantics, and the owner-only authorization requirement. It does not describe the not-found outcome, which is the remaining gap.

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

Conciseness5/5

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

Three sentences, front-loaded with the action and mechanism, then the state effect, then the operational caveats (rate limit, owner-only). No filler or repetition of the title.

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?

With an output schema present, return values need no explanation, and the auth, rate-limit, and verification-mechanism details make this callable as-is. The only omission is the failure path when the token is absent, a minor gap for a single-parameter tool.

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

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (id) at 100% schema description coverage, so the schema already carries the semantics and the description adds no format or constraint detail beyond what is there. Baseline 3 is appropriate; no parameter value is misdescribed.

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?

Names a specific verb (check/verify) and resource (a merchant's previously requested domain verification token), and the phrase 'previously requested' cleanly separates it from the sibling insumer_request_domain_verification without needing the schema.

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 prerequisite ordering is clear: this checks a token that was already requested, and the 'Owner only' note plus the 429/retry guidance set invocation context. It stops short of explicitly naming the sibling or stating what to do if the token is not found.

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