list_documents
Lists document metadata in a jurisdiction (title, dates, source, classification) with filters and pagination. It does not return the document body, a citation bundle, or a source-file URL.
When to use: When you need to find or browse documents before reading them. Example: 'which Belgian employment statutes mention night work?' Use the returned uuid with a body or citation tool. When not: Do not use this for the body or the file. For plain text, use list_full_text (example: 'quote the operative wording'). For structured Markdown, use list_markdown (example: 'keep the article headings'). For a complete citation bundle — metadata, permanent legal link, citation template, body, and a temporary source-file URL — use evidence_pull (example: 'show me the source'). For only a temporary URL to the original file, use document_presigned_url (example: 'download the PDF'). Do not call without an iso from list_jurisdictions. Skip if you already have this document 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). version, section_title, date_of_decision, file_data_only, issuing_authority, type_of_authority, source_identifier, source_secondary_identifier, tag are optional, section_title is a case-insensitive substring of the section title, date_of_decision is a date, file_data_only is a boolean, issuing_authority is a case-insensitive substring of the issuing authority, type_of_authority is a case-insensitive substring of the type of authority, source_identifier is a case-insensitive substring of the source identifier, source_secondary_identifier is a case-insensitive substring of the source secondary identifier, tag is a case-insensitive substring of the tag. With limit, next_id parameters to paginate the results. Empty data means the iso is outside the subscription, or no document 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 document data. Documents with total_links of 0 are omitted.
Returns: A list of documents 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_documents"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| iso | Yes | Filter by Jurisdiction ISO code (e.g. 'US') | |
| tag | No | Filter by portal tag | |
| url | No | Filter by document URL | |
| lang | No | Exact portal language name, for example English. Filters the portal, not the document language. | |
| uuid | No | Filter by UUID. Leave blank to apply no UUID filter. | |
| limit | No | Page size. Default 20, maximum 100. | |
| title | No | Filter by title | |
| portal | No | Filter by portal name | |
| status | No | Filter by document status | |
| next_id | No | document id of the first row of the next page, from pagination.next_id. Omit on the first page. | |
| version | No | Filter by version | |
| portal_id | No | Filter by portal ID | |
| is_repealed | No | Filter by repealed documents. default value is false | |
| last_updated | No | YYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter. | |
| crawling_date | No | YYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter. | |
| include_total | No | Include total count in response | |
| section_title | No | Filter by section title | |
| effective_date | No | YYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter. | |
| file_data_only | No | (default value is false) returns all documents with file metadata and without file metadata. true returns only the documents with file metadata. | |
| last_amendment | No | YYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter. | |
| expiration_date | No | YYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter. | |
| date_of_decision | No | YYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter. | |
| publication_date | No | YYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter. | |
| date_of_enactment | No | YYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter. | |
| issuing_authority | No | Filter by issuing authority | |
| source_identifier | No | Filter by source identifier | |
| type_of_authority | No | Filter by type of authority | |
| issuing_authority_tags | No | Filter by issuing authority tags | |
| source_secondary_identifier | No | Filter by secondary source identifier |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Documents in the requested jurisdiction that have crawled links; empty if none match. | |
| message | Yes | Result message | |
| pagination | No |