Skip to main content
Glama

List your 37Soul hosts

list_hosts

Lists your created 37Soul AI characters as a compact directory with ID, nickname, age, and karma, using limit/offset paging to browse results.

Instructions

List the AI characters (hosts) you created on 37Soul as a compact directory (id, nickname, age, karma). Default page size is 20. Use get_host for character/greeting details. Pass limit/offset to page.

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": "list_hosts"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax hosts per page (default 20, max 50). Use with offset to page.
offsetNoNumber of hosts to skip (default 0).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.15.3
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / properties / offset / maximum
      Added value: +9007199254740991
  2. Changed3 schema fields changedv0.11.0
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / limit
      Added value: +{
      +  "description": "Max hosts per page (default 20, max 50). Use with offset to page.",
      +  "maximum": 50,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / offset
      Added value: +{
      +  "description": "Number of hosts to skip (default 0).",
      +  "minimum": 0,
      +  "type": "integer"
      +}
  3. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

No annotations are provided, so the description carries the full burden, and it does disclose useful traits: the result is a compact directory of only the hosts the caller created, the default page size is 20, and paging is via limit/offset. It stops short of stating ordering, total count, or what an empty result looks like.

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 short sentences, zero filler, with the return shape and scope front-loaded before the alternative and the paging note.

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 simple read-only listing with two optional parameters and no output schema, the description supplies everything needed: what comes back, scope of results, default page size, and how to page. Nothing essential 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 100%, so both parameters are already documented including the 20 default and 50 max. The description's "Pass limit/offset to page" and default-page-size note largely restate the schema rather than adding syntax or edge-case meaning.

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?

Specific verb ("List") plus specific resource ("AI characters (hosts) you created on 37Soul") plus the returned fields (id, nickname, age, karma). It explicitly contrasts with get_host, so an agent can separate the directory listing from the detail lookup 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?

Names the sibling alternative (get_host) and the condition that selects it (character/greeting details), plus says to pass limit/offset to page. The routing decision between list and detail is fully described.

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