Lawstronaut

list_subdomains

Read-onlyIdempotent

Lists subdomains under one domain (id, domain_id, subdomain_id, subdomain name). This is the second taxonomy step.

When to use: When you already have a domain_id from list_domains. Examples: 'subdomains under domain A', 'international law under Private law'. Pass subdomain only to narrow by name. When not: Do not call without a domain_id from list_domains; use list_domains first. For categories under a subdomain use list_categories with subdomain_id. For subcategories use list_subcategories. For law types use list_law_types. For documents use list_documents or search. Skip if you already have this subdomain list for the same domain_id and subdomain filter.

Parameters: domain_id (required) is the domain reference from list_domains, such as A, and is uppercased before the query. It is not the numeric id. subdomain is an optional case-insensitive substring of the subdomain name. An unknown domain_id returns Domain not found. limit defaults to 20 and is capped at 100. next_id is the numeric id from pagination.next_id, not subdomain_id. Empty data means that domain has no matching subdomain.

Behavior: Read-only SELECT; does not create, update, or delete records, files, or credentials. The only effect is a database read. Auth: tools/call requires OAuth 2.0 or a Bearer token (401 if missing, invalid, revoked, or no active subscription). Rate limits: none at the MCP layer; safe to retry. Not cached; each call reads the current subdomain table. total_count is the full match count, not the page size.

Returns: A page of {id, domain_id, subdomain_id, subdomain}. Example: {"id":1,"domain_id":"A","subdomain_id":"A.1","subdomain":"Private International Law"}. Pass subdomain_id, not id, to list_categories.

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

Input Schema

Name	Required	Description
`limit`	No	Number of results to return
`next_id`	No	Next ID to paginate the results
`domain_id`	Yes	Filter by Domain ID
`subdomain`	No	Filter by subdomain name

Output Schema

Name	Required	Description
`data`	Yes	Subdomains in the requested domain that have data; empty if none match.
`message`	Yes	Result message
`pagination`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedNov 9, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

removedInput schema / additionalProperties
```
Removed value: -false
```

addedInput schema / properties / next_id

Added value: +{
+  "description": "Next ID to paginate the results",
+  "type": "number"
+}

removedInput schema / properties / offset

Removed value: -{
-  "description": "Number of results to skip",
-  "type": "number"
-}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "data": {
+      "description": "Subdomains in the requested domain that have data; empty if none match.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "domain_id": {
+            "description": "Parent domain reference, such as A",
+            "type": "string"
+          },
+          "id": {
+            "description": "Numeric row id. Use only as pagination.next_id, not as subdomain_id.",
+            "type": "number"
+          },
+          "subdomain": {
+            "description": "Subdomain display name, or null when unset",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "subdomain_id": {
+            "description": "Subdomain reference, such as A.1. Pass this to list_categories as subdomain_id.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "domain_id",
+          "subdomain_id",
+          "subdomain"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "message": {
+      "description": "Result message",
+      "type": "string"
+    },
+    "pagination": {
+      "additionalProperties": false,
+      "properties": {
+        "limit": {
+          "description": "Maximum number of subdomains returned",
+          "type": "number"
+        },
+        "next_id": {
+          "description": "Cursor ID for the next page, or null when there is no next page",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "total_count": {
+          "description": "Total number of matching subdomains",
+          "type": "number"
+        }
+      },
+      "required": [
+        "total_count",
+        "limit",
+        "next_id"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "message",
+    "data"
+  ],
+  "type": "object"
+}

First observedJul 8, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations' readOnlyHint/destructiveHint/idempotentHint, the description discloses that this is a read-only SELECT with no side effects, that auth requires OAuth 2.0 or a Bearer token with specific 401 conditions, that there are no MCP-layer rate limits and retries are safe, that results are not cached, and that total_count is the full match count rather than the page size. That is substantial context an agent could not infer from the annotation block alone.

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 text is front-loaded with purpose and usage, then cleanly sectioned into When to use, Parameters, Behavior, and Returns, so an agent can scan to the relevant part. It is longer than strictly necessary and repeats some safety information already carried by the annotations, which keeps it just short of a 5.

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 four-parameter paged list tool with an output schema, the description covers everything needed: prerequisites, error cases, pagination semantics, field meanings, a literal response example, and the handoff instruction to pass subdomain_id rather than id to list_categories. Nothing material is left to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is already 100%, the description adds meaning the schema does not: domain_id is a domain reference like 'A' that is uppercased before querying and is explicitly not the numeric id; subdomain is a case-insensitive substring; limit defaults to 20 and is capped at 100; next_id must come from pagination.next_id and is not subdomain_id. It also documents the 'Domain not found' outcome and the meaning of empty data.

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 description opens with a specific verb and resource ('Lists subdomains under one domain') and names the exact fields returned. It also positions the tool in a taxonomy sequence ('This is the second taxonomy step'), which lets an agent distinguish it from list_domains, list_categories, and the other list siblings without opening a 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?

It gives explicit when-to-use guidance ('When you already have a domain_id from list_domains') with concrete examples, explicit when-not ('Do not call without a domain_id from list_domains; use list_domains first'), and routes each adjacent need to the correct sibling: list_categories for categories, list_subcategories for subcategories, list_law_types for law types, list_documents/search for documents. It even states a skip condition for redundant calls.

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

All Lawstronaut tools Inspect

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.