List documents
list-documentsGet 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 / search-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:
Split the request into its conditions. "what logo usage rights do we have for our largest customers?" is three: "logo usage rights", "largest", "customers".
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.
Look up the candidates with the companion tools above, then filter with the matching filter_ parameter.
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: search-external-parties
filter_automations: search-automations
filter_document_types: list-account-document-types
filter_document_users: search-document-users
filter_imports: search-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 search-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.
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-documents"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Which page of results to fetch | |
| include | No | Optional sections to include for each document, on top of the default compact summary. Allowed values: parties (the contracting entities, in compact form), teams (the teams the document is assigned to), tags (the account classification labels on the document — useful for seeing which categories the account actually uses), details (origin, locale and source template), signing_settings (signature type, sequential signing and the external signatory invitation message), timestamps (created_at, updated_at and archived_at — the last of these tells an archived document from an active one). Only request the sections you actually need; use get-document-info for full information about a single document. | |
| sort_by | No | Sort results by this field. The default is: updated_at. Allowed values are any of the static sort fields (name, stage, created_at, updated_at, archived_at, relevance) or any metadata field `name` from list-account-metadata | |
| per_page | No | How many results to return on each page. Defaults to 10, or - when filter_document_uuids is used - to the number of UUIDs given, so that one response covers them all | |
| filter_tags | No | A list of tag UUIDs (find them with list-account-tags). Tags are the account's own classification labels, commonly covering relationship type (customer, supplier, partner), commercial significance (key account, strategic), lifecycle or region. When a user groups documents by a category — "our customers", "vendor contracts", "strategic accounts" — that category is often a tag, so check list-account-tags before treating it as free text. The default behavior is to match documents that have ANY of the given tags | |
| filter_query | No | A fuzzy full-text relevance search across document name, plaintext content and other indexed fields (metadata, parties, etc). Because it is fuzzy, it is NOT a reliable way to filter by a specific structured attribute such as a metadata value, party, document user or document type — for those, use the matching filter_ parameter instead. Prefer filter_query only for genuine free-text searches or when searching by document name. If sort_by is not provided, results will be returned most relevant first | |
| filter_teams | No | A list of team UUIDs (find them with list-account-teams). Matches documents assigned to any of the given teams | |
| filter_joined | No | If true, finds documents the current user has joined, i.e. is an owner or collaborator on. If false, finds documents the current user has not joined yet (including documents they are on only as signatory), which join-document still makes them a collaborator on. Omit to apply no filtering by joined state. Use false before joining several documents with join-document, so documents already joined are not joined again. Joining a document removes it from a filter_joined=false result, which moves the remaining documents to earlier pages: after joining the documents of a page, request page 1 again rather than the next page, until total is 0. The in_app_url does not apply this filter | |
| filter_stages | No | A list of document stages. Matches documents that are in ANY of the given stages | |
| filter_expired | No | If true, finds documents with an expiration date in the past. If false, excludes documents with an expiration date in the past (documents without an expiration date count as not expired). Omit to apply no expiry filtering | |
| filter_imports | No | A list of import UUIDs (find them with search-imports). Matches documents that came from any of the given imports | |
| filter_locales | No | A list of either document language locale codes (e.g. "en-US", "de-DE") or the special value "has_no_value". Matches documents whose language is any of the given locales. "has_no_value" finds documents with no language set | |
| filter_origins | No | A list of document origins. Matches documents with ANY of the given origins | |
| filter_tag_and | No | If true, changes filter_tags behavior to only match documents that have ALL of the given tags. Sending false or omitting this filter has no effect | |
| sort_direction | No | The default is: desc | |
| filter_metadata | No | Filter by metadata field values. Discover field names, value_type and select_values with list-account-metadata. Each entry in filter_metadata must name one field and provide exactly one matcher appropriate to that field type | |
| filter_templates | No | A list of template UUIDs (find them with list-templates). Matches documents created from any of the given templates | |
| include_metadata | No | Metadata field `name`s (from list-account-metadata) to return a value for on every document in the response, up to 10 fields. Use this whenever you need the same metadata for several documents — it answers the whole question in one call, instead of calling get-document-info once per document. Each requested field is returned for every document, with a null value where that document has no value for it. Only request the fields you actually need: values are returned per document, so the response grows with per_page × the number of fields | |
| filter_automations | No | A list of automation UUIDs (find them with search-automations). Matches documents created by any of the given automations | |
| filter_discussions | No | `has_any` will find documents that have at least one discussion (regardless of current status). `has_open` will find only documents that have at least one open discussion | |
| filter_excluded_tags | No | A list of tag UUIDs (find them with list-account-tags). Documents with ANY of these tags will be excluded from the result | |
| filter_archived_state | No | Which documents to return, by archived state. "active" (the default) returns only active, non-archived documents; "archived" returns only archived documents; "all" returns both. Use "all" whenever the answer is meant to cover a complete set or a count of documents ("all our NDAs", "how many contracts with Acme"): archiving is not deletion, so an archived document is still a real agreement and leaving it out under-reports the answer. Use "archived" only when the user asks specifically about archived documents. With "all" the response does not say which results are archived unless you also request include=["timestamps"]: archived_at is set on an archived document and null on an active one | active |
| filter_document_types | No | A list of document type UUIDs (find them with list-account-document-types). Matches documents of any of the given types | |
| filter_document_users | No | A list of document users (find them with search-document-users). Matches documents that any of the given people are on. Use this when looking for documents involving a specific named individual (such as a signatory or contact): that person is distinct from a party, and may sign or act on behalf of a party (e.g. a business) without being a party themselves. Provide first_name and last_name as returned by search-document-users | |
| filter_document_uuids | No | A list of document UUIDs, up to 50. Restricts the results to those documents. Use this when you already know which documents you are interested in — for example to fetch include_metadata values, parties or tags for a set of documents whose UUIDs you have from earlier in the conversation — instead of calling get-document-info once per document. Unless you set per_page yourself, the page is sized to the list so a single response covers every UUID you sent. UUIDs that do not exist, or that the current user cannot access, simply do not appear in the results, so do not assume every UUID you send is returned | |
| filter_account_parties | No | A list of account party UUIDs (find them with list-account-parties). Account parties are the account's OWN entities — the company the user belongs to and its subsidiaries/group companies ("our" company, "our subsidiary"), as opposed to external parties (filter_external_parties), which are the counterparties on the other side. Matches documents that involve any of the given account parties. A party is a contracting entity (often a business/organization) and is distinct from the individual people on a document — to find documents involving a specific named person, use filter_document_users instead | |
| filter_team_unassigned | No | If true, finds documents, that are not assigned to any team. May be combined with the filter_teams filter to find documents that are in the given filter_teams OR are unassigned. Sending false or omitting this filter has no effect | |
| filter_external_parties | No | A list of external party names (the entity_name returned by search-external-parties). External parties are the counterparties on the other side of an agreement (entities that do NOT belong to the account), as opposed to account parties (filter_account_parties), which are the account's own entities ("our" company and its subsidiaries). Matches documents that involve any of the given external parties. A party is a contracting entity (often a business/organization) and is distinct from the individual people on a document — to find documents involving a specific named person, use filter_document_users instead |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| total | No | How many documents are available across all pages | |
| max_page | No | How many pages of results are available | |
| documents | No | ||
| in_app_url | No | A URL that opens the fynk app's documents list with the same filters, sorting and pagination applied. Give this to the user when they may want to view or work with this filtered document list in the fynk app | |
| current_page | No | Which page of results this is |