Skip to main content
Glama
Aidress-ai

Aidress

Official
by Aidress-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

rotate_agent_key

Request a new bearer key for a specified Aidress agent; the old key stops working once the new key is claimed.

Instructions

Request rotation of an agent's bearer key — the previous key stops working the moment the new one is actually claimed (see claim_bearer_key).

Auth, in the order the server checks it:

  • Ed25519 signature (RFC 9421). Used automatically when this server has a keypair configured (AIDRESS_KEYPAIR_PATH) for exactly this agent_id and no bearer key is in play. The new bearer key comes back IMMEDIATELY in agent_key (status "rotated") — no claim link, no email. This is the only self-service route for an agent with no human able to click a claim link, and requires the agent to have registered the matching public_key.

  • Org key. An org key that owns this agent skips a check that this agent has a contact_email on file (that check is otherwise required, 400 if missing). On the hosted remote connector, send your org's X-API-KEY header on the MCP connection itself; locally, set AIDRESS_API_KEY in the server environment.

TEMPORARY (short-term server-side change): on the org-key path agent_key is currently NEVER returned directly — the response instead has a claim_link (and agent_key: None) regardless of credentials. Pass the token from that link to claim_bearer_key to actually mint and receive the key. The signature path above is unaffected.

agent_id — the agent whose bearer key to rotate.

Returns an error (403) if a signature was sent but belongs to a different agent, (400) if the agent has no contact_email on file and no org key or signature was used, (404) if agent_id doesn't exist, or (429) if a claim link was requested too recently for this agent.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
agent_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.4.1

TDQS

A4.4/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so richly: it discloses the ordering of server-side auth checks, the immediate-return behavior on the signature path, a TEMPORARY server-side behavior change overriding normal output, rate limiting (429) on claim-link requests, and specific failure codes (403/400/404). This is unusually thorough behavioral disclosure.

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?

The purpose and key-lifecycle constraint are front-loaded, and the auth-path list and error list are well separated with structure. It is long and slightly dense, with return-field behavior split across two places (the signature path paragraph and the TEMPORARY notice), but nearly every sentence is load-bearing for a security-sensitive operation.

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 a complex, security-critical mutation with no output schema and no annotations, the description covers return fields (agent_key, status 'rotated', claim_link), the current override behavior, auth prerequisites, and error conditions. Nothing an agent needs in order to call it correctly is missing.

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?

Schema description coverage is 0% and there is only one parameter; the description defines agent_id as 'the agent whose bearer key to rotate', which adds modest meaning beyond the bare 'Agent Id' title. It gives no format, example, or lookup guidance, so it only partially compensates for the coverage gap.

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 states a specific verb and resource ('Request rotation of an agent's bearer key') and immediately clarifies the key lifecycle ('the previous key stops working the moment the new one is actually claimed'). It explicitly routes the reader to the sibling claim_bearer_key, so an agent can distinguish the two without opening either 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?

It clearly describes the conditions selecting each auth path and states that the signature route is 'the only self-service route for an agent with no human able to click a claim link', which is strong context. It does not, however, contrast against other key-manipulation siblings such as set_agent_key, so the when-not guidance is incomplete.

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

Deploy Server

Other Tools