Skip to main content
Glama
Sign In

kya-brasil

by io.github.celfons
OverviewDiscussionsAdmin

kya_register

Register an AI agent for a Brazilian company: agent key (EVM address or Web Bot Auth Ed25519 key), CNPJ and a mandate (JSON, validated against /.well-known/kya-mandate.schema.json). Returns a one-time challenge the agent signs with its key and the company signs with its e-CNPJ (CMS/PKCS#7). Price covers the checks at issuance.

Input Schema

NameRequiredDescriptionDefault
cnpjNoThe company's CNPJ (company agents). Leave out with principal "person".
agentYes
mandateYesMandate JSON validated by https://kya-br-agents.marcelfons.workers.dev/.well-known/kya-mandate.schema.json. Reserved fields: actions, max_per_operation, max_per_day, currencies, counterparties, valid_from, valid_until.
principalNo"person": the agent acts for a natural person who signs with an e-CPF (no CNPJ; no name or CPF is ever published).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / cnpj / description
      Previous value: -"The company's CNPJ, with or without punctuation."New value: +"The company's CNPJ (company agents). Leave out with principal \"person\"."
    • addedInput schema / properties / principal
      Added value: +{
+  "description": "\"person\": the agent acts for a natural person who signs with an e-CPF (no CNPJ; no name or CPF is ever published).",
+  "enum": [
+    "company",
+    "person"
+  ],
+  "type": "string"
+}
    • changedInput schema / required
      Previous value: -[
-  "agent",
-  "cnpj",
-  "mandate"
-]New value: +[
+  "agent",
+  "mandate"
+]
  2. Changed4 schema fields changed
    • changedInput schema / properties / agent / properties / id / description
      Previous value: -"0x address for evm; base64url raw Ed25519 public key for web-bot-auth."New value: +"0x address for evm; base64url raw Ed25519 public key for web-bot-auth; eip155:<chainId>:<identityRegistry>:<agentId> for erc8004."
    • changedInput schema / properties / agent / properties / id / maxLength
      Previous value: -128New value: +160
    • changedInput schema / properties / agent / properties / kind / description
      Previous value: -"evm: an Ethereum-style wallet (EIP-191 signatures). web-bot-auth: an Ed25519 key (RFC 9421 / Web Bot Auth)."New value: +"evm: an Ethereum-style wallet (EIP-191 signatures). web-bot-auth: an Ed25519 key (RFC 9421 / Web Bot Auth). erc8004: an agent registered in an ERC-8004 Identity Registry; its on-chain agentWallet signs."
    • changedInput schema / properties / agent / properties / kind / enum
      Previous value: -[
-  "evm",
-  "web-bot-auth"
-]New value: +[
+  "evm",
+  "web-bot-auth",
+  "erc8004"
+]
  3. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations only supply openWorldHint=true, so the description carries real weight and delivers it: a one-time challenge, a dual signing flow (agent key + company e-CNPJ via CMS/PKCS#7), and a pricing note. It stops short of covering idempotency, reversibility, or what happens after the challenge is signed.

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, front-loaded with the purpose and followed by the return/signing behavior and the pricing note; little waste. The pricing sentence is arguably extra but is useful context for an agent deciding to proceed.

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 no output schema, the description rightly explains the return value (a one-time challenge) and the signing sequence. For a multi-party, nested-object registration flow it is fairly complete, though it could point to the follow-up sibling tool needed to complete registration.

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 75%, so the schema already documents most fields; the description nonetheless reinforces the agent-key formats (EVM address, Web Bot Auth Ed25519) and the mandate's schema validation. It omits the erc8004 key kind that the schema allows, a minor gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Register an AI agent for a Brazilian company', and enumerates the required inputs (agent key, CNPJ, mandate). It implicitly separates itself from siblings like kya_renew and kya_revoke by naming the registration operation, though it never names an alternative tool explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The context of registering a company agent is implied, and the schema's 'principal'/'person' detail suggests a person variant, but the description never states when to use this versus kya_renew, kya_company_agents, or kya_person_agents, nor any prerequisite (e.g., that it is the first step before kya_prove).

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

All kya-brasil toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources