Skip to main content
Glama

list_portals

Read-onlyIdempotent

Lists the source portals available through this tool, with metadata such as jurisdiction and language. A jurisdiction may have multiple portals, including those maintained by regulators or ministries.

When to use: When you need portals, legal websites, or sources for a known iso. Pass optional name, tag, or lang only to narrow that list. When not: Do not use this to read a document. For metadata use list_documents. For plain text use list_full_text. For structured Markdown use list_markdown. For a complete citation bundle use evidence_pull. For a temporary source-file URL use document_presigned_url. Do not call without an iso from list_jurisdictions. Skip if you already have this portal list for the same iso and filters.

Parameters: iso (required) is a jurisdiction code from list_jurisdictions (e.g. BE, or US_CA for a state). name, tag, and lang are optional and combined with AND: name is a case-insensitive substring of the portal name, tag must match one portal tag exactly, lang must match the language name exactly (e.g. English). With limit, next_id parameters to paginate the results. Empty data means the iso is outside the subscription, or no portal with crawled links 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 current subscription and portal data. Portals with total_links of 0 are omitted.

Returns: A list of portals matching the filters, with pagination information.

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

Input Schema

NameRequiredDescriptionDefault
isoYesiso (required) is a jurisdiction code from list_jurisdictions (e.g. BE, or US_CA for a state).
langNoExact language name, e.g. English
nameNoCase-insensitive substring of the portal name
limitNoNumber of portals to return
next_idNoNext portal ID to return
portal_idNoPortal ID
portal_tagsNoExact portal tag; the portal must include this tag
advanced_searchNoAdvanced search enabled

Output Schema

NameRequiredDescriptionDefault
dataYesPortals in the requested jurisdiction that have crawled links; empty if none match.
messageYesResult message
paginationNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 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 / description
      Added value: +"iso is required. name, tag, and lang are optional AND filters. Scope is the authenticated subscription."
    • addedInput schema / properties / advanced_search
      Added value: +{
      +  "default": false,
      +  "description": "Advanced search enabled",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / iso / description
      Previous value: -"Filter by Jurisdiction ISO code (e.g. 'US')"New value: +"iso (required) is a jurisdiction code from list_jurisdictions (e.g. BE, or US_CA for a state)."
    • changedInput schema / properties / lang / description
      Previous value: -"Filter by language"New value: +"Exact language name, e.g. English"
    • addedInput schema / properties / limit
      Added value: +{
      +  "description": "Number of portals to return",
      +  "type": "number"
      +}
    • changedInput schema / properties / name / description
      Previous value: -"Filter by portal name"New value: +"Case-insensitive substring of the portal name"
    • addedInput schema / properties / next_id
      Added value: +{
      +  "description": "Next portal ID to return",
      +  "type": "number"
      +}
    • addedInput schema / properties / portal_id
      Added value: +{
      +  "description": "Portal ID",
      +  "type": "number"
      +}
    • addedInput schema / properties / portal_tags
      Added value: +{
      +  "description": "Exact portal tag; the portal must include this tag",
      +  "type": "string"
      +}
    • removedInput schema / properties / tag
      Removed value: -{
      -  "description": "Filter by portal tags",
      -  "type": "string"
      -}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "data": {
      +      "description": "Portals in the requested jurisdiction that have crawled links; empty if none match.",
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "advanced_search": {
      +            "description": "Advanced search enabled",
      +            "type": [
      +              "boolean",
      +              "null"
      +            ]
      +          },
      +          "documents_count": {
      +            "description": "Number of documents in the portal",
      +            "type": "number"
      +          },
      +          "jurisdiction": {
      +            "additionalProperties": false,
      +            "description": "Jurisdiction this portal belongs to",
      +            "properties": {
      +              "country": {
      +                "description": "Country name",
      +                "type": "string"
      +              },
      +              "iso": {
      +                "description": "Jurisdiction ISO",
      +                "type": "string"
      +              },
      +              "state": {
      +                "description": "State or region name; empty string when the portal is national",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              }
      +            },
      +            "required": [
      +              "iso",
      +              "country"
      +            ],
      +            "type": "object"
      +          },
      +          "language": {
      +            "description": "Language name, e.g. English",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "name": {
      +            "description": "Portal name in the source language",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "name_en": {
      +            "description": "English name, or null when the portal has none",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "portal_id": {
      +            "description": "Portal ID",
      +            "type": "number"
      +          },
      +          "portal_tags": {
      +            "anyOf": [
      +              {
      +                "items": {
      +                  "type": "string"
      +                },
      +                "type": "array"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ],
      +            "description": "Tags on the portal; null when none are set"
      +          },
      +          "url": {
      +            "description": "Portal base URL",
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "portal_id",
      +          "url",
      +          "jurisdiction",
      +          "documents_count"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "message": {
      +      "description": "Result message",
      +      "type": "string"
      +    },
      +    "pagination": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "limit": {
      +          "description": "Maximum number of portals 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 portals",
      +          "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 read-only, idempotent, non-destructive, open-world, so the description goes further: OAuth/Bearer auth with 401 semantics and subscription gating, no MCP-layer rate limits, safe to retry, no caching, and the non-obvious data rules (portals with total_links 0 omitted, empty data means out-of-subscription or no crawled links). This is substantive context beyond structured fields.

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 segmented into When to use / When not / Parameters / Behavior / Returns, with the core purpose front-loaded. A few lines are near-redundant with annotations or schema, such as 'The only effect is a database read' following the read-only declaration, which keeps it from 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?

Given eight parameters, a 100%-covered schema, an output schema, and sibling routing, the definition covers everything an agent needs: prerequisite source for iso, filter semantics, auth failure mode, retryability, empty-result interpretation, and omitted portals. Return shape is correctly deferred to the output schema.

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% (baseline 3), and the description adds real meaning: the AND combination of name/tag/lang, case-insensitive substring vs exact-match semantics, a concrete example (English, BE, US_CA), and pagination via limit/next_id. It loses a point for calling the parameter 'tag' when the schema names it 'portal_tags', and for leaving portal_id and advanced_search unaddressed.

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 ('Lists the source portals'), explains what a portal is (jurisdiction, language metadata, regulator/ministry-maintained), and contrasts with all relevant siblings (list_documents, list_full_text, list_markdown, evidence_pull, document_presigned_url). An agent can distinguish this from every named alternative 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?

Explicit 'When to use' and 'When not' blocks, each with a named alternative and its purpose, plus a prerequisite (iso from list_jurisdictions) and an anti-redundancy rule ('Skip if you already have this portal list for the same iso and filters'). Nothing is left to inference.

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.