Skip to main content
Glama
Sign In

Lawstronaut

by com.lawstronaut
OverviewDiscussionsAdmin

list_domains

Read-onlyIdempotent

Lists the top-level legal domains (id, domain_id, domain name). This is the first taxonomy step. It does not return subdomains, categories, documents, or jurisdictions.

When to use: When you need the domain list or a name match. Examples: 'what legal domains exist?', 'find the domain for private law'. Pass domain only to narrow by name. When not: Do not use this for children of a domain. For subdomains use list_subdomains with the returned domain_id. For categories use list_categories. For subcategories use list_subcategories. For law types use list_law_types. For documents use list_documents or search. For jurisdictions use list_jurisdictions. Skip if you already have this domain list for the same domain filter.

Parameters: domain is an optional case-insensitive substring of the domain name. There is no parent id and no iso. limit defaults to 20 and is capped at 100. next_id is the numeric id from the previous pagination.next_id; omit it on the first page. A null next_id means there is no further page. Empty data means no domain name matched.

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 domain table. total_count is the full match count, not the page size. Results are not limited to a jurisdiction.

Returns: A page of {id, domain_id, domain}. Example: {"id":1,"domain_id":"A","domain":"Private law"}. Pass domain_id, not id, to list_subdomains.

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_domains"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoNumber of results to return
domainNoFilter by domain name
next_idNoNext ID to paginate the results

Output Schema

NameRequiredDescriptionDefault
dataYesTop-level domains; empty if none match. Not limited to a jurisdiction.
messageYesResult message
paginationNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • 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": "Top-level domains; empty if none match. Not limited to a jurisdiction.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "domain": {
+            "description": "Domain display name, or null when unset",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "domain_id": {
+            "description": "Domain reference, such as A. Pass this to list_subdomains as domain_id.",
+            "type": "string"
+          },
+          "id": {
+            "description": "Numeric row id. Use only as pagination.next_id, not as domain_id.",
+            "type": "number"
+          }
+        },
+        "required": [
+          "id",
+          "domain_id",
+          "domain"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "message": {
+      "description": "Result message",
+      "type": "string"
+    },
+    "pagination": {
+      "additionalProperties": false,
+      "properties": {
+        "limit": {
+          "description": "Maximum number of domains returned",
+          "type": "number"
+        },
+        "next_id": {
+          "description": "Numeric id cursor for the next page, or null when there is no next page",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "total_count": {
+          "description": "Total number of matching domains",
+          "type": "number"
+        }
+      },
+      "required": [
+        "total_count",
+        "limit",
+        "next_id"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "message",
+    "data"
+  ],
+  "type": "object"
+}
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered; the description still adds material context beyond that: OAuth/Bearer auth with the specific 401 failure modes, no MCP-layer rate limits and safe retry, no caching (each call reads the live table), and pagination termination semantics ('A null next_id means there is no further page'). It also explains that empty data means no name match rather than an error.

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?

Well front-loaded: purpose, then when/when-not, then parameters, behavior, and returns, so an agent can stop reading early. It is on the verbose side, and parts overlap structured data — the read-only disclaimer repeats readOnlyHint, and the Returns block largely restates the output schema, though the 'Pass domain_id, not id, to list_subdomains' note earns that section its place.

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 three-optional-parameter list tool in a crowded taxonomy family, nothing an agent needs is missing: routing to every sibling level, pagination loop termination, filter syntax, auth failure modes, and the id vs domain_id handoff. Output schema exists and the description appropriately limits its return coverage to the one non-obvious handoff detail.

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% but the schema descriptions are thin ('Number of results to return'), and the description meaningfully upgrades them: domain is an optional case-insensitive substring, limit defaults to 20 and is capped at 100, next_id is the numeric id from the prior page and must be omitted on the first page. It does not fully restate the parameter names as a mapping, so it is additive rather than exhaustive.

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 first sentence states a specific verb and resource ('Lists the top-level legal domains') plus the returned fields, and immediately scopes it negatively ('does not return subdomains, categories, documents, or jurisdictions'). That negative scoping alone separates it from the many sibling list_* tools 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 Guidelines5/5

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

It gives an explicit when-to-use section with example queries, an explicit when-not section, and names the correct alternative for each adjacent taxonomy level (list_subdomains, list_categories, list_subcategories, list_law_types, list_documents, list_jurisdictions). It even adds a skip condition ('Skip if you already have this domain list for the same domain filter'), which is rare and useful.

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

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