Skip to main content
Glama

Register a canary (operator session required)

canary_register
Idempotent

Needs a Desk session (Authorization: Bearer); without one this returns 401. Register the public part of a decoy you planted: kind address|key|url|apikey|tool|x402 with exactly one target (address, url_sha256, key_sha256, tool_name or resource_path), a label, the triggers to watch (nonce, code, permit, siwe, inbound_transfer, http_hit, api_use, tool_call, x402_request) and planted_at. Needs Authorization: Bearer ; the session's wallet is the operator. Private material is refused before validation; a bait key must be fresh (nonce 0, no code). A canary is a decoy you plant where only an intruder or a misled agent would read it: a bait key that never holds a balance (its first use is the signal), an address planted as a treasury, a URL, an API key, a tool description or a paid x402 resource. Register the PUBLIC part only (address, hash, tool name, path); we refuse anything that looks like a key, a URL or an API key in clear. We read the chain every 2 minutes (nonce, code, gas funding, inbound transfers, permits) and your own channels when you push them (canary ingest). A fire is a pattern for a human to read, written to your canary log; nothing is published about a plant. Live since 1 Nov 2026 (shadow 16 Oct - 1 Nov): at most 25 live canaries per operator; fires reach you through canary_status, not by e-mail yet.

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": {
      "registration": "<registration>"
    },
    "name": "canary_register"
  }
}

Input Schema

NameRequiredDescriptionDefault
registrationYes{canary_id (32-64 hex), kind, label, watch[], planted_at, and one of address | url_sha256 (+url_host) | key_sha256 | tool_name (+description_sha256) | resource_path (+price)}

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.3/5.0
Behavior5/5

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

Goes well past the annotations: 401 without a Bearer session, operator identity taken from the session wallet, refusal of private material before validation, freshness precondition for bait keys, a 25-live-canary cap per operator, a 2-minute chain read cadence, and the fact that nothing about a plant is published. Annotations only say it is a non-readonly, idempotent, non-destructive write; the description supplies the auth, limits and side-effect profile the agent needs.

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

Conciseness2/5

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

The auth requirement is stated twice ('Needs a Desk session (Authorization: Bearer); without one this returns 401' and again 'Needs Authorization: Bearer <Desk session>'), and the canary definition is restated after already being given. The operational facts are valuable but buried in a long, unstructured block with rollout dates and shadow-mode notes that do not help an agent decide how to call it.

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?

For a mutation tool with no output schema, it covers auth, preconditions, quotas, detection cadence and where results surface (canary_status, not e-mail), which is nearly everything an agent needs. The remaining gap is that it never says what a successful registration returns or acknowledges the required canary_id field.

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 already 100% and the nested registration object is documented, but the description adds meaning the schema lacks: the full trigger vocabulary (nonce, code, permit, siwe, inbound_transfer, http_hit, api_use, tool_call, x402_request) and the exactly-one-target rule across address, url_sha256, key_sha256, tool_name and resource_path. It does not mention canary_id, which the schema requires inside registration.

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 ('Register the public part of a decoy you planted') and immediately enumerates what a canary is and what kinds exist (address|key|url|apikey|tool|x402). It is clearly separable from the sibling canary_status, which is named as the read-back channel rather than the registration path.

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 concrete conditions: you must have a Desk session, you register only a decoy you actually planted, and fires are read through canary_status or pushed via canary ingest. It also states a hard exclusion (private material is refused before validation; a bait key must be fresh with nonce 0 and no code), though it never frames an explicit 'use X instead when Y' alternative beyond canary_status.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.