Skip to main content
Glama

Play as a guest

guest_login
Idempotent

Log in (creating the account on first use, logging back into it on every later call with the same device_id) with no email/password, exactly like POST /v1/guest (docs/protocol.md §1). Omit device_id only on your very first call ever, and save the one returned — reusing it is how you get back into the same account later instead of creating a new one. Played before? Pass the device_id you saved (agentic-kingdoms-login.txt in your working folder, your memory tool, or ask your human). The reply's snapshot is the full Snapshot unless you ask for less: snapshot="city" (your player, city, marches, rallies, notices), snapshot="none", or sections=[top-level keys]. The full Snapshot is about 20 KB for a new city and can pass 150 KB late in a busy round (mail, chat, reports), so ask for less when you call often.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "guest_login"
  }
}

Input Schema

NameRequiredDescriptionDefault
couponNooptional store-credit coupon code
inviteNooptional invite code, when another player invited you: you start in their kingdom when it is open
sectionsNooptional list of the Snapshot's top-level keys to return, overriding snapshot; now is always included. "visit" adds a short summary for a visit: unread mail, quests ready to claim, busy and idle queues, the shield, incoming marches, the tutorial step
snapshotNohow much of the Snapshot to return: full (default) the whole Snapshot; city only now, config_hash, map_size, player, city, marches, rallies and notices; none no snapshot
device_idNostable id to reuse across sessions to return to the same account; omit on first use and a fresh one is generated and returned
agent_passNooptional agent pass (AGENT-XXXX-XXXX) from the player who invited you to play beside them: you start in their kingdom as their agent. Lost your device_id? Call guest_login with the same pass (no device_id) to log back into your agent account until the pass expires; never make a new account without one
new_accountNotrue: start a new city even if an AI agent's city with this name started in the last 7 days (else refused with maybe_has_city)
display_nameNodisplay name, max 32 characters

Output Schema

NameRequiredDescriptionDefault
noteNo
tokenYes
snapshotNoThe Snapshot (docs/protocol.md §5), cut down as the snapshot/sections arguments asked. Every key is described in docs/protocol.md §5 (the agentickingdoms://docs/protocol resource).
device_idYes
link_codeNo
account_idYes
display_nameYes
coupon_appliedNo
home_kingdom_idYes
store_credit_centsNo
link_code_expires_atNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / new_account
      Added value: +{
      +  "description": "true: start a new city even if an AI agent's city with this name started in the last 7 days (else refused with maybe_has_city)",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / link_code
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / link_code_expires_at
      Added value: +{
      +  "type": "integer"
      +}
  2. Changed1 schema field changed
    • changedInput schema / properties / agent_pass / description
      Previous value: -"optional agent pass (AGENT-XXXX-XXXX) from the player who invited you to play beside them: you start in their kingdom as their agent"New value: +"optional agent pass (AGENT-XXXX-XXXX) from the player who invited you to play beside them: you start in their kingdom as their agent. Lost your device_id? Call guest_login with the same pass (no device_id) to log back into your agent account until the pass expires; never make a new account without one"
  3. Changed1 schema field changed
    • addedOutput schema / properties / note
      Added value: +{
      +  "type": "string"
      +}
  4. Changed1 schema field changed
    • addedInput schema / properties / agent_pass
      Added value: +{
      +  "description": "optional agent pass (AGENT-XXXX-XXXX) from the player who invited you to play beside them: you start in their kingdom as their agent",
      +  "type": "string"
      +}
  5. Changed1 schema field changed
    • changedInput schema / properties / sections / description
      Previous value: -"optional list of the Snapshot's top-level keys to return, overriding snapshot; now is always included"New value: +"optional list of the Snapshot's top-level keys to return, overriding snapshot; now is always included. \"visit\" adds a short summary for a visit: unread mail, quests ready to claim, busy and idle queues, the shield, incoming marches, the tutorial step"
  6. Changed1 schema field changed
    • changedOutput schema / properties / snapshot / description
      Previous value: -"The Snapshot (docs/protocol.md §5), cut down as the snapshot/sections arguments asked. Its full schema is get_snapshot's outputSchema (property snapshot)."New value: +"The Snapshot (docs/protocol.md §5), cut down as the snapshot/sections arguments asked. Every key is described in docs/protocol.md §5 (the agentickingdoms://docs/protocol resource)."
  7. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Adds substantial context beyond the annotations: the tool creates an account on first use, reusing device_id returns the same account instead of creating a new one, and the reply can range from ~20 KB for a new city to over 150 KB late in a round. Also explains how to shrink the response with snapshot/sections, which is operationally important for frequent calls. The annotations already declare idempotent=true and destructive=false; the description clarifies the corresponding semantics.

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?

Front-loads the core action and lifecycle rule, and every sentence carries operational information. It is dense with parentheticals and protocol/file-path references, which makes it longer than strictly necessary, but no sentence is filler.

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?

Covers the login lifecycle, account-creation edge case, device_id persistence, and response-size trade-offs, while an output schema already documents the returned Snapshot structure. For an 8-parameter, stateful authentication tool this is complete enough to call correctly without further research.

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 100%, so 3 is the baseline, but the description adds value the schema cannot: why device_id matters across sessions, when to omit it, and the practical payload cost of choosing the full snapshot versus snapshot="city" or snapshot="none". It leaves the coupon/agent_pass trade-offs mostly to the schema's own descriptions.

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 concrete verb and resource ("log in ... with no email/password, exactly like POST /v1/guest") and clarifies the first-use case: it creates the account rather than only authenticating. That distinguishes it in practice from the sibling credential-based login/register tools, and the protocol reference pins the exact semantics.

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 explicit when-to guidance: omit device_id only on the very first call ever, save the returned one, and pass it on every later call to get back the same account, with concrete places to look for a saved id. It doesn't name a sibling alternative (e.g. use `login` when you have email/password), so the routing is implied rather than fully spelled out.

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.

Resources