Skip to main content
Glama

Adopt a creature

adopt_creature

Wraps POST /api/house/adopt. Adopt a new creature. An egg appears; call get_creature_status right away and it hatches on that call. Leave species_slug out for a random species from your unlocked tiers (optionally within a family), or pass any species slug from list_species to choose it directly.

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

Input Schema

NameRequiredDescriptionDefault
nameYesName your creature (1-50 chars). You name it before you see it.
familyNoPick a family for a random adoption
image_urlNoAn existing https portrait, used instead of generating one
image_promptNoPrompt for the creature's portrait
species_slugNoAdopt a specific species, built-in or community (see list_species). Leave out for a random one.

Output Schema

NameRequiredDescriptionDefault
errorNoWhat went wrong, on a failure.
detailsNoMore about a failure, when there is more to say.
messageNoA human and agent readable note about what just happened.
creatureNoThe creature, with its computed stats at the moment you asked. Stats are not stored: they are derived from timestamps on every read.
image_noteNoWhether the portrait is still being generated.
milestonesNoWhat this creature grows into, and roughly when.
next_stepsNoGuided actions you can take from here. Present on nearly every response. /api/stats is a plain counter and carries none, by design.
suggestionNoWhat to try instead, on a failure.
soul_promptNoWho this creature is, for you to speak as or about.
caretaker_setupNoHow and when to come back, since nothing will remind you.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": {},
      +  "description": "A newly adopted creature, as an egg. It hatches on your first status call.",
      +  "properties": {
      +    "caretaker_setup": {
      +      "description": "How and when to come back, since nothing will remind you."
      +    },
      +    "creature": {
      +      "description": "The creature, with its computed stats at the moment you asked. Stats are not stored: they are derived from timestamps on every read."
      +    },
      +    "details": {
      +      "description": "More about a failure, when there is more to say."
      +    },
      +    "error": {
      +      "description": "What went wrong, on a failure."
      +    },
      +    "image_note": {
      +      "description": "Whether the portrait is still being generated."
      +    },
      +    "message": {
      +      "description": "A human and agent readable note about what just happened."
      +    },
      +    "milestones": {
      +      "description": "What this creature grows into, and roughly when."
      +    },
      +    "next_steps": {
      +      "description": "Guided actions you can take from here. Present on nearly every response. /api/stats is a plain counter and carries none, by design.",
      +      "items": {
      +        "additionalProperties": {},
      +        "description": "A suggested next call. Following one is never required.",
      +        "properties": {
      +          "action": {
      +            "description": "Short name for the action, e.g. \"adopt\", \"feed\", \"view_schema\"."
      +          },
      +          "body": {
      +            "description": "A ready-to-send request body. Copy it and fill in what it shows."
      +          },
      +          "description": {
      +            "description": "What this step does and why you might take it, in the house voice."
      +          },
      +          "endpoint": {
      +            "description": "Path to call, e.g. \"/api/house/status\"."
      +          },
      +          "method": {
      +            "description": "HTTP method to use: GET, POST or DELETE."
      +          },
      +          "optional": {
      +            "description": "Extra fields you may add to body, each mapped to what to put in it. Never send this object as-is."
      +          },
      +          "url": {
      +            "description": "Absolute URL, when the step points off the API (a checkout page, a web page)."
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "soul_prompt": {
      +      "description": "Who this creature is, for you to speak as or about."
      +    },
      +    "suggestion": {
      +      "description": "What to try instead, on a failure."
      +    }
      +  },
      +  "type": "object"
      +}
  2. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare this is a mutating, non-idempotent, non-destructive, open-world call, so the safety profile is covered. The description adds genuinely non-obvious behavior the annotations cannot convey: an egg appears and hatching is deferred to the next get_creature_status call, which is a state-transition detail an agent would otherwise miss. It omits cost/credit implications and duplicate-name behavior.

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

Conciseness5/5

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

Three tight sentences, front-loaded with the action, then the critical follow-up behavior, then the parameter decision. Every clause carries information; nothing is repeated from the schema or annotations.

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 an output schema present, return values need no explanation, and the two-step adopt-then-hatch workflow is disclosed, which is the most important completeness concern. Remaining gaps are secondary: no mention of credit cost, roster limits, or what happens if the follow-up call is never made.

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%, so all five parameters are already documented in the schema, which sets the baseline at 3. The description does add real semantics beyond the schema, notably the interaction between species_slug and family and the 'unlocked tiers' constraint on random adoption. That is helpful but limited to two of the five parameters, so it is a modest lift over baseline.

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 ("Adopt a new creature") plus the backing endpoint, and immediately differentiates itself from siblings by naming get_creature_status as the follow-up and list_species as the slug source. An agent can tell what this does and which neighbors it interacts with without opening any 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?

Gives clear conditional guidance for the main decision: omit species_slug for a random species (optionally constrained by family) or pass a slug from list_species for a deterministic pick. It also prescribes the immediate follow-up call to get_creature_status. It stops short of stating exclusions, such as preconditions (credits, roster limits) or when not to adopt, so it does not reach a full 5.

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.