Read tools
These tools only look. Every connected app gets them, and they are the only tools an app has unless an administrator has agreed it may make changes.
compute_expression
Section titled “compute_expression”Evaluate a math expression with arbitrary-precision decimal arithmetic. Use this for any sum / average / difference / multiplication / percentage calculation. NEVER compute math in your head — this tool is always cheaper and always correct.
Expression grammar:
- Operators: + - * / and parentheses
- Functions: sum(a, b, …), avg(a, b, …), min(a, b, …), max(a, b, …), abs(x), round(value, places)
- Numbers can be decimal (e.g. 89.50, -1.25)
Examples:
- “1250 + 89.50 + 12450.75” → “13790.25”
- “sum(1250, 89.50, 12450.75)” → “13790.25”
- “avg(45.50, 127.80, 2234.00)” → “802.4333”
- “(1250 + 89.50) * 1.20” → “1607.40”
- “round((45.50 + 127.80) / 3, 2)” → “57.77”
- “max(1250, 89.50, 12450.75)” → “12450.75”
| Argument | Type | Required | What it is |
|---|---|---|---|
expression | string | Yes | The math expression to evaluate. |
scale | integer | No | Decimal places of precision (0-20). Default 4. For currency, prefer 2 or 4. |
filter_by_field
Section titled “filter_by_field”Find files where one or more custom fields match. Automatically detects similar values (typos, OCR errors, abbreviations) and includes them in the results. Use list_fields first to get field IDs. Pass filters as a JSON array, e.g. [{“field_id”:“X”,“value”:“Y”}]. For AND across multiple fields: [{“field_id”:“X”,“value”:“Y”},{“field_id”:“Z”,“value”:“W”}]. In your response, always mention any variant matches found.
To compute a sum/avg/min/max over the matched files (e.g. “total spend where status=paid”), pass aggregate as a JSON object: {“field_id”:“<numeric field id>”,“op”:“sum|avg|min|max”}. The aggregate runs server-side — never sum results yourself. If the aggregate field isn’t numeric, the response will include aggregate.reason: 'field_not_numeric' and you should tell the user the field can’t be summed.
| Argument | Type | Required | What it is |
|---|---|---|---|
filters | string | Yes | JSON array of filters, e.g. [{“field_id”:“29”,“value”:“paid”}] |
aggregate | string | No | Optional JSON object: {“field_id”:“30”,“op”:“sum”}. Op is one of sum|avg|min|max. |
get_file_info
Section titled “get_file_info”Get the details of one file or folder in a share: its name, kind, size, last-modified time and type.
| Argument | Type | Required | What it is |
|---|---|---|---|
share | string | Yes | The share’s name or id, from list_shares |
path | string | Yes | Path of the file or folder inside the share |
get_indexed_content
Section titled “get_indexed_content”Get the text Foldr’s search index extracted from a file (including OCR of scans), without opening the file itself. Only for shares that list_shares marks indexed.
A long text comes back in parts: when next_offset is set, call again with offset set to it.
| Argument | Type | Required | What it is |
|---|---|---|---|
share | string | Yes | The share’s name or id, from list_shares |
path | string | Yes | Path of the file inside the share |
offset | integer | No | Where to start, from a previous part’s next_offset (default 0) |
get_my_activity
Section titled “get_my_activity”Get your recent activity across all shares. Filter by action type and/or a relative time window.
| Argument | Type | Required | What it is |
|---|---|---|---|
type | string | No | Optional: download, upload, delete, share, view, create |
since | string | No | ISO date or relative like ‘last week’, ‘yesterday’ |
limit | integer | No | Maximum events to return (default 50, max 200) |
get_my_shared_items
Section titled “get_my_shared_items”Get items you have shared with others. An item with pending_approval true is a request still waiting for an approver: nobody else can open it yet, and the people or public link it asks for are not in effect until it is approved.
| Argument | Type | Required | What it is |
|---|---|---|---|
recipient_guid | string | No | Filter by recipient: the person’s or group’s guid, when you already have it |
type | string | No | Filter: file, dir, or public |
expired | string | No | Filter: true (expired only) or false (active only) |
get_shared_with_me
Section titled “get_shared_with_me”Get items others have shared with you.
| Argument | Type | Required | What it is |
|---|---|---|---|
sharer_guid | string | No | Filter by who shared: the person’s guid, when you already have it |
type | string | No | Filter: file or dir |
list_bookmarks
Section titled “list_bookmarks”List your bookmarks. Optionally filter by filename.
| Argument | Type | Required | What it is |
|---|---|---|---|
search | string | No | Optional filename substring |
list_fields
Section titled “list_fields”List available custom fields across all your shares.
No arguments.
list_folder
Section titled “list_folder”List the files and folders in one folder of a share, folders first, 200 entries per page.
When next_page is set there are more entries: call again with that page. When truncated is true the folder holds more entries than can be listed, and the pages cover only the first of them.
| Argument | Type | Required | What it is |
|---|---|---|---|
share | string | Yes | The share’s name or id, from list_shares |
path | string | No | Folder path inside the share; ”/” or empty for the top of the share (default ”/”) |
page | integer | No | Page number, from 1 (default 1) |
list_shares
Section titled “list_shares”List the shares (storage locations) you can read. Call this first: every other file tool takes a share’s name or id from this list.
Each share has its name, id, storage type, whether it is indexed for search_files, and whether it is read-only for you.
A share listed with reachable: false is one of yours whose file server could not be reached just now (it timed out or refused the connection). It exists and you may read it, but it cannot be opened or searched until the server is back: tell the user it is unavailable, not that it does not exist, and try again in a few minutes.
No arguments.
list_versions
Section titled “list_versions”List the earlier versions of one file, newest first, each with the id restore_version_as_copy takes, when it was saved, its size and, where Foldr recorded it, who saved it. Only storage that keeps versions has any (SharePoint, S3 when the bucket is versioned, Azure, Foldr’s hosted storage, SMB shadow copies); other storage answers that it keeps none.
| Argument | Type | Required | What it is |
|---|---|---|---|
share | string | Yes | The share’s name or id, from list_shares |
path | string | Yes | Path of the file inside the share |
read_file
Section titled “read_file”Read a file’s text. Plain-text files (txt, csv, md, json, code…) are read as they are; documents (PDF, Word, Excel, PowerPoint…) give their extracted text, from the search index when it has it.
A file with no text (an image, a video, an archive) is answered with its size and type instead, never raw bytes. A long file comes back in parts: when next_offset is set, call again with offset set to it to read on.
| Argument | Type | Required | What it is |
|---|---|---|---|
share | string | Yes | The share’s name or id, from list_shares |
path | string | Yes | Path of the file inside the share |
max_bytes | integer | No | Most text to return for a plain-text file, in bytes (default 49152, at most 61440) |
offset | integer | No | Where to start, from a previous part’s next_offset (default 0) |
search_field_values
Section titled “search_field_values”Search for existing values of a custom field. Use to browse what values exist for a field, or to check for a specific value with a prefix filter. Returns up to 100 distinct values.
| Argument | Type | Required | What it is |
|---|---|---|---|
field_id | string | Yes | The field ID from list_fields |
prefix | string | No | Starting characters to filter by (e.g. “A”, “Acm”) |
search_files
Section titled “search_files”Search file names and contents with Foldr’s keyword search, across every indexed share you can read or within one share. Only files you are allowed to see are returned.
Plain words find files containing all of them; “quoted phrases” match exactly. Each hit has its share, path, name, size, modified time and a snippet of matching text; pass its share and path to read_file to read it.
| Argument | Type | Required | What it is |
|---|---|---|---|
query | string | Yes | What to search for |
share | string | No | Limit the search to this share (name or id from list_shares); empty for all indexed shares |
page | integer | No | Page number, from 1 (default 1) |
limit | integer | No | Hits per page (default 20, at most 50) |
whoami
Section titled “whoami”Get the current user’s profile: name, email, type, group memberships, admin status, and enabled tier features. Useful for “what groups am I in?”, “am I an admin?”, “what features do I have?”.
No arguments.