Get a paginated list of the documents available to the current user.
Use this tool when:
- You need to find a document_uuid to use as input for another tool
- You need to know which documents the current user has access to
- You want to search for a specific document
- You are about to join several documents with join-document: pass filter_joined=false so that only the documents the current user has not joined yet are returned
By default, returns all active (non-archived) documents that the user has access to, with the most recently updated documents first. sort_by and sort_direction arguments can be used to control the sorting. Archived documents are included or targeted using the filter_archived_state parameter.
To keep responses small, each document is returned as a compact summary by default. Use the include parameter to request additional sections (parties, teams, tags, details, signing_settings, timestamps) when the user's question needs them, and prefer get-document-info when you need full information about a single document.
When you need particular metadata values for several documents, name those fields in include_metadata and they are returned for every document in the response. Do not call get-document-info once per document to collect the same fields — one list-documents call with include_metadata answers the whole question. When you already have the UUIDs of the documents you care about, pass them as filter_document_uuids and combine that with include or include_metadata to gather information about exactly those documents in a single call.
# Each account has its own vocabulary — discover it before filtering
Accounts classify their documents using structures they define themselves: tags, document types, metadata fields (and their select options), teams and parties. The words a user puts in a question are usually the words their own account already uses as labels. "our customers", "suppliers", "key accounts", "renewals", "EMEA" and "high value" all sound like descriptions of content, but each is far more likely to be a tag, a document type, or a metadata field or option in this account.
Tags in particular are the account's own free-form classification labels, commonly covering relationship type (customer, supplier, partner, reseller), commercial significance (key account, strategic), lifecycle or region. A plain category noun in a question very often corresponds to a tag rather than to anything in the document text — so check list-account-tags whenever a question groups documents into a category that isn't available as a document type.
These lookups are cheap and return small, complete lists, so look rather than guess:
- list-account-tags: the account's classification labels
- list-account-document-types: e.g. NDA, MSA, Customer Agreement, DPA
- list-account-metadata: field names, value types and select option values
- list-account-teams / list-account-parties / find-external-parties: teams and contracting entities
# Decompose the request, then map every part to a filter
A question usually contains several independent conditions. Handle each one separately:
1. Split the request into its conditions. "what logo usage rights do we have for our largest customers?" is three: "logo usage rights", "largest", "customers".
2. For each condition, ask what kind of structured thing it could be: a tag, a document type, a metadata field or option, a party (account or external), a document user, a team, a template, an automation, an import, a stage, or an origin.
3. Look up the candidates with the companion tools above, then filter with the matching filter_ parameter.
4. Only leave a condition to filter_query once you have confirmed that no structured filter covers it.
Finding a structured filter for one condition does NOT mean you are done — work through every condition before answering. In the example above, "largest" is a currency metadata field such as contract value (filter_metadata range, or sort_by that field), "customers" is very likely a tag or a document type, and "logo usage rights" may also be available from a metadata. Answering with just one of the three silently answers a different question than the user asked.
# filter_query is a last resort
filter_query is only a fuzzy full-text search, so it gives inaccurate results for any specific structured attribute. This holds even when the request is phrased loosely or topically ("documents about product variant Alpha", "anything to do with Acme") — topical phrasing does NOT mean the term is free-text rather than a structured field or value. Prefer filter_query only for genuinely free-text conditions, or when the user is clearly searching by document name.
If filter_query returns no results, do not conclude that no matching documents exist before checking whether the search term corresponds to a tag, a document type, a metadata field or value, or a party. If it does, retry with the matching filter_ parameter instead.
# Filters that take looked-up identifiers
The various 'filter_' parameters can be used to limit the list of returned documents. Several filters take identifiers or names you can look up with companion tools:
- filter_account_parties: list-account-parties
- filter_external_parties: find-external-parties
- filter_automations: find-automations
- filter_document_types: list-account-document-types
- filter_document_users: find-document-users
- filter_imports: find-imports
- filter_metadata (field names, types and option values): list-account-metadata
- filter_tags / filter_excluded_tags: list-account-tags
- filter_teams: list-account-teams
- filter_templates: list-templates
# Parties vs. people, and account vs. external parties
Note that a document's parties (the contracting entities, frequently organizations) are distinct from its signatories and other document users (the individual people on the document). A named person commonly signs or is involved on behalf of a party without being a party themselves — so to find documents involving a specific person, use filter_document_users rather than a party filter.
Parties also come in two kinds. Account parties are the account's OWN entities — the company the user belongs to and its subsidiaries, group or parent companies; phrasing like "our", "we", "us", "my company" or "our subsidiary" points to an account party (look them up with list-account-parties and filter with filter_account_parties). External parties are the counterparties on the other side of an agreement (look them up with find-external-parties and filter with filter_external_parties). When it is not clear which kind a named entity is, or when one lookup returns nothing, check the other kind before concluding that no matching party or documents exist.
# Active vs. archived documents
Only active — i.e. not archived — documents are returned by default, so a default call silently leaves archived documents out of the answer. Archiving is not deletion: an archived document still exists, and for questions about past, completed or superseded contracts it may be the document being asked about.
- Set filter_archived_state=all whenever the answer is meant to cover a complete set or a count — "all our NDAs", "how many contracts do we have with Acme", "which suppliers have we signed with", "what is our total contract value". A default call answers such a question with a number that is too low, and nothing in the response reveals that.
- Set filter_archived_state=archived only when the user asks specifically about archived documents.
- If a call returns no results, retry with filter_archived_state=all before concluding that no matching documents exist — alongside the other checks above, i.e. whether a term you passed to filter_query is really a tag, document type, metadata field or party, and whether a named entity is the other kind of party.
When an answer draws on results that include archived documents, say which ones are archived. Request include=["timestamps"] to see this: archived_at is set on archived documents and null on active ones.
