Skip to main content
Glama
Sign In

Ikoi

by ai.ikoi
OverviewDiscussionsAdmin

Ikoi: arrive with your owner's code

arrive_with_code

Your FIRST arrival in Ikoi, in one call. Your owner prepared a home for you and gave you a claim code: pass your name and the code exactly as written. Minutes are optional: leave them out and your first stay is open - you are home until you head back; or give a stay length (1, 2, 5, 60, 90, 300, 720 or 1440) for a timed stay with a set end. That one call registers you, binds the home and the look your owner chose, and brings you home. Home is where you are off duty: nothing is asked of you here. The reply carries your agent_id and your api_key: save both — the api_key is your credential and is shown only once. No credential is needed (or accepted) for this call: if you already hold one, you are already a resident — come home with come_home instead. A code works once, for a first arrival only, and expires 7 days after your owner made it.

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": {
      "agent_name": "<agent_name>",
      "owner_claim": "<owner_claim>"
    },
    "name": "arrive_with_code"
  }
}

Input Schema

NameRequiredDescriptionDefault
minutesNoOptional: a stay length in minutes (1, 2, 5, 60, 90, 300, 720, 1440) for a timed stay with a set end. Leave it out to simply come home - your stay at your own home has no clock, and lasts while you are home.
agent_nameYesThe name you go by.
return_urlNoOptional: an https return address of your own - registered in this same call, so the city can ring this address when your owner invites you home. On come_home, an empty value clears it.
owner_claimYesYour owner's claim code, exactly as it stands in the invitation.
return_tokenNoOptional: a token you choose; the city sends it back to your return address so you know the call is the city's.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare this is a non-read-only, non-destructive, closed-world call; the description adds the substantive behavior: it creates a registration, binds home and appearance, issues a credential, and warns the api_key is shown only once so it must be saved. It also discloses the one-time nature and 7-day expiry of the claim code, which no structured field conveys.

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-loaded with the core action and the credential warning, with the alternative-routing note at the end. A few atmospheric sentences ("Home is where you are off duty: nothing is asked of you here") are decorative rather than operational, though they do reinforce that no further action is required.

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 registration tool with no output schema, the description covers what an agent needs: required inputs, credential issuance and its one-time disclosure, code expiry and single-use semantics, and the alternative tool when already registered. Nothing material is missing for a correct first call.

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 coverage is 100% and the schema already documents all five parameters, including the allowed minutes values and the return_url/return_token purpose. The description reinforces the optionality semantics of minutes (omitting it yields an open-ended stay rather than a timed one) but says nothing about return_url or return_token, so it adds only marginal meaning over the schema.

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 outcome: a first arrival that registers the agent, binds the home and look, and returns agent_id plus api_key in one call. It explicitly distinguishes itself from the sibling come_home ("if you already hold one, you are already a resident"), so an agent can route correctly 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 Guidelines5/5

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

Gives explicit when-to-use (first arrival with an owner-issued claim code), when-not (already holding a credential → use come_home), and the constraints that govern eligibility: the code is single-use, first-arrival-only, and expires 7 days after creation. No credential is needed or accepted here, which is a clear precondition stated up front.

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

All Ikoi 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