add_file
ChatGPTAdd a file to the user's private Wordsmith space from a public https URL, a host attachment, or text. Returns the file's Wordsmith id. URLs over 100 MB, slow downloads, and private or non-https addresses are refused. For text with format=docx, write Markdown; Wordsmith converts it to Word formatting. When to use - The user attached a file, gives a public link, or you have a document's text, and it should be in Wordsmith. When NOT to use - To ask Wordsmith a question about an attachment straight away. Pass it to ask_wordsmith in files, which imports it. - The file is on the user's machine and you can run curl. Call create_file_upload, which keeps it intact.
ask_wordsmith
ChatGPTAsk a Wordsmith agent to do legal work in conversation: answer a question, draft, redline or summarise. Covers legal, contract, compliance and policy questions, and questions about the user's organisation: its documents, agents, playbooks and blueprints. The agent works from the user's playbooks, blueprints and knowledge base. It does not answer general-knowledge questions with no legal or organisational angle. Its result is the agent's answer as text. A playbook review, with findings by severity and a redline, is review_document. The call waits up to wait_seconds for the answer. An answer that uses tools often takes several minutes, so it usually returns status: "in_progress" with an operation_id: call get_operation with it, which waits up to 20 seconds per call, until the answer is ready. A finished answer lists any files it produced (attachments), each with a file_id for read_file. status: "filtered" means the agent declined the question: show the answer and do not poll. Pass the returned session_id back to ask a follow-up. To give the agent documents, pass host attachments in files and Wordsmith file ids in file_ids (at most 10 in all). Attaching files needs the files:write scope, and file_ids also files:read. When to use - The user wants Wordsmith to answer, draft, redline or summarise legal work. - The user asks about their organisation's documents, agents or playbooks. When NOT to use - To review a contract against a playbook or the user's checks: review_document. - General knowledge outside legal work, such as recipes, travel or trivia: outside Wordsmith's scope. - To fetch the answer to a question already asked. Call get_operation with its operation_id.
cancel_operation
ChatGPTStop long-running work a tool started. Best-effort: work already done, such as computed report cells, is kept. Only use it when the user asks to stop.
complete_file_upload
ChatGPTFinish an upload started with create_file_upload, after the PUT succeeded, and get the file's id. The returned id is the Wordsmith file id that ask_wordsmith (file_ids), the task tools and the file read tools take. An expired or unknown upload_id is an error: start again with create_file_upload. Completing the same upload again returns the same file. When to use - The PUT to upload_url returned 200. When NOT to use - Before the PUT: the file is not there yet. Run the curl_command from create_file_upload first.
create_file_upload
ChatGPTGet a one-time URL to upload a local file into the user's private Wordsmith space. Three steps: call this, PUT the file's bytes to upload_url (curl_command is the exact command, with <path> for the file), then call complete_file_upload with upload_id. The URL works for 10 minutes. A sandboxed host may need the URL's storage domain allow-listed for the PUT. When to use - You can run shell commands (curl) and the user wants a local file in Wordsmith. When NOT to use - The file is a host attachment, at a public https URL, or you only have its text. Call add_file.
create_task
ChatGPTCreate a Wordsmith task, optionally assigned to a person, an agent or a team. People, agents and teams can be named by id, email or name, and the user as "me"; an ambiguous name is an error that lists the matches. Set parent_task_id to create a subtask. When to use - The user wants to log, delegate or track a piece of work in Wordsmith. When NOT to use - To change an existing task. Call update_task.
draft_document
ChatGPTDraft a new Word or PDF document in Wordsmith. Without blueprint_id it drafts from your instructions and context. With a blueprint_id it fills the blueprint: from values alone when they cover every required placeholder, otherwise it drafts the missing values from the context, files or session you give. Waits up to wait_seconds for the document. If it is still running, call get_operation with the operation_id. On success, result holds file_id (read it with read_file), the values used for a blueprint so the user can check them, and url, which opens the draft in Wordsmith. Use ask_wordsmith instead to review, redline or answer a question about a document.
find_resources
ChatGPTList or search Wordsmith objects of one kind: the agents the user can ask, playbooks, blueprints, skills, repositories of documents, reports, document reviews, the user's past conversations (session), or the organisation's members, teams, roles and company profiles. Use it to find the id another tool needs, such as an agent_id for ask_wordsmith or a person to share with. Returns summaries; read one in full with get_resource. To list tasks, call find_tasks.
find_tasks
ChatGPTList the Wordsmith tasks the user can see, newest first, with filters and a pagination cursor. Pass the returned cursor back to get the next page; a null cursor is the last page. With no person filter the list includes other people's tasks. For the user's own tasks, pass assigned_to: "me", or involving: "me" for every task they take part in. When to use - The user asks what tasks they have, or looks for tasks by person, status, due date or text. When NOT to use - The user names one task (#123). Call get_resource with kind="task".
get_document_changes
ChatGPTFor Wordsmith's own views: a DOCX's tracked changes, one per changed paragraph, and comments.
get_operation
ChatGPTWait for long-running work a tool started, such as a review, a document transform, a report run or an answer. Pass the operation_id it returned. Waits up to wait_seconds (default 20) and returns as soon as the work finishes, with its result. Such work often takes several minutes: status running means Wordsmith is still working, so call it again.
get_resource
ChatGPTRead one Wordsmith object in detail by kind and id: an agent, a playbook with its checks, a blueprint with its placeholders, a skill with its instructions and files, a repository, a document review, a past conversation, a task, a report with its columns, a member with their roles and teams, a team with its members, a role, or a company profile. include adds lists such as a review's findings, a report's cells, a task's comments or who an object is shared with.
get_review
ChatGPTRead a review: its status, finding counts and redline file, and a page of its findings (issues by default), each with its explanation, cited text and proposed amendments. A counterparty_edits review has one finding per change: the counterparty's edit, the recommendation (accept, reject, amend, reply or escalate), our counter_proposal and the suggested_reply. Pass finding_status='all' to see every change, accepted ones included. While the review is queued or running its findings are incomplete, and get_operation with its operation_id returns when it finishes.
get_usage
ChatGPTRead Wordsmith usage and value: sessions, active users, hours saved and cost saved. Use it when the user asks how much they or their organisation use Wordsmith, or what it saved. scope=company and breakdowns need permission to view company analytics.
legal_research
ChatGPTSearch case law and legislation in public legal databases, or read one document's text. Sources: moonlit (legislation in 30+ jurisdictions, strongest in civil-law Europe), courtlistener (US case law), uk_case_law, uk_legislation, nz_legislation, eur_lex (EU law and CJEU), federal_register, regulations_gov and sec_edgar (US). action="search" searches every source at once. sources gives each one's status: timeout for a slow source, which does not fail the search, and partial when some of its matches may be missing. action="read" takes source and document_id from a result. A non-null next_offset means more text: call again with offset=next_offset. sec_edgar results cannot be read; give the user their url. When to use - The user wants cases, statutes or regulations on a point, or the text of a judgment or Act. When NOT to use - The user wants a researched answer or memo. Call ask_wordsmith.
manage_report
ChatGPTBuild and run a Wordsmith report: a grid of documents (rows) by questions (columns), where each cell is the AI's answer to its column's question for its row's document. Actions: - create: name, description, and repository_id (rows follow the repository) or file_ids; optional columns. With file_ids, run=true also starts the run, without waiting for it. - update: report_id, name and/or description. - add_columns: report_id, columns. - add_rows: report_id, file_ids. Not for a report whose rows follow a repository. - run: report_id, optional row_ids and column_ids. Computes every cell not done yet and uses credits. - export: report_id, format. The operation's result has the exported file's file_id. A report created with repository_id has no operation and needs no run: its rows and cells fill in the background, usually within a minute or two. Until then, get_resource(kind="report", include=["cells"]) shows fewer rows than the repository has documents, or cells that are empty, pending or computing. Its sync_status is syncing while its rows are brought in line with the repository, synced once they match, and failed if the sync stopped; a failed report fills no further. In a report made from file_ids, new columns and rows stay empty until a run. run and export return an operation: if it is still running, call get_operation with its operation_id. Read the answers with get_resource(kind="report", include=["cells"]). When to use - The user wants the same questions answered across many documents, e.g. a lease or contract abstract. When NOT to use - One question about one or two documents. Call ask_wordsmith.
manage_repository
ChatGPTCreate or change a repository of documents: create one, rename it, add files to it, create a folder, or remove one document. add_files turns uploaded files into searchable documents and returns a repository_indexing operation; when it is still running, call get_operation. Each file moves into the repository, and remove_document deletes the document and its file. Deleting a whole repository is not available here. When to use - The user asks to set up a repository, file documents into one, or take a document out. When NOT to use - To search documents. Call search_knowledge. - To get a file into Wordsmith first. Call add_file or create_file_upload, then add_files.
manage_skill
ChatGPTCreate or change one of the user's Wordsmith skills: instructions the Wordsmith agent follows when a request matches the skill's description, with bundled files such as references and scripts. - create: name, description and instructions, or skill_md: a SKILL.md with YAML front matter (name, description) and the instructions as its body. Optional files. New skills are private. - update: skill_id and only what changes. files adds a file or replaces the one at its path; remove_files detaches paths. To import a skill folder, upload every file but SKILL.md with add_file or create_file_upload, then pass files as {path, file_id}, e.g. references/policy.md. Read skills with get_resource(kind=skill).
read_file
ChatGPTRead a Wordsmith file: its metadata, a page of its plain text, or a download link. For text, a non-null next_offset means there is more: call again with offset=next_offset. A download returns two links: url works without sign-in and expires in 5 minutes, so fetch it straight away; web_url asks for Wordsmith sign-in and does not expire, so it is the one to show the user. When to use - You have a file id and need to know what it is, read or quote it, or the user wants the file itself. When NOT to use - To have Wordsmith analyse the file. Call ask_wordsmith with the id in file_ids.
reply_to_task_requester
ChatGPTSend a reply to the person who requested a Wordsmith task, on the task's conversation thread. The reply leaves Wordsmith: the requester receives it, usually by email. To attach files, pass file_ids from add_file or complete_file_upload. When to use - The user wants to answer or update the requester. When NOT to use - For a note the requester must not see. Call add_task_comment.
review_document
ChatGPTReview contracts against one of the user's playbooks, against checks built from instructions you write, or, with counterparty_edits, the other side's tracked changes and comments in one DOCX of the user's own paper (a Redline Review: party required, playbook and instructions optional). A playbook holds the organisation's positions on one type of contract, and a playbook review compares the documents with every check in it. It returns findings by severity, each with an explanation, cited text and any proposed amendment, and a redline. Pass Wordsmith file ids: add the files, including chat attachments, with add_file first. A review takes minutes: get_operation with its operation_id returns when it finishes, and its findings are complete once status is succeeded. Then read them with get_review. The review works on copies of the files, so its file_ids differ from the ones you pass.
search_knowledge
ChatGPTSearch the organisation's repositories of documents by meaning and return the best-matching passages. Each passage carries its repository_id, document_id, file_id and a score from 0 to 1. Without repository_ids it searches the 20 most recently used repositories the user can read; searched_repository_ids lists the ones covered. Read a whole file with read_file and its file_id. file_id is null for a document synced from a connector or an older one with no file. read_file cannot open it, so work from the passage. When to use - The user asks what their own documents, precedents or past agreements say about a topic. When NOT to use - To list repositories or their documents. Call find_resources or get_resource with kind=repository. - For case law or legislation. Call legal_research.
share_resource
ChatGPTShare a repository, report, playbook, blueprint or task with a person or team in the user's organisation, take their access away, or set whether everyone in the organisation can see it. Use it when the user asks to share something or change who can see it. The user must be allowed to manage the object's sharing. Nothing is shared outside the organisation or made public.
transform_document
ChatGPTMake a new document from Wordsmith files: compare two versions, edit one from instructions as tracked changes, translate, redact, convert between DOCX and PDF, accept all tracked changes, or merge files into one PDF. The inputs are not changed. Pass file ids from the file tools; the result's file_ids are the new files, readable with read_file. Waits up to wait_seconds. If status is still running, call get_operation with the operation_id. When to use - The user wants one of these actions done to files they have in Wordsmith, as a file. When NOT to use - To review a contract against a playbook, or to explain the differences in chat. Call ask_wordsmith.
update_review
ChatGPTAct on a finished review. generate_redline makes a new tracked-changes DOCX from the chosen findings' proposed amendments (a ZIP of DOCX files when they change several documents), and returns its file_id when done. For a counterparty_edits review it applies decisions instead: accept, reject, amend (with the counter_proposal), reply or skip per change, to the original document. The review's own redline, with every recommendation applied, is already in get_review's redline_file_id.
update_task
ChatGPTChange a Wordsmith task: status, priority, assignees, due date, tags, draft or archived state; attach files, add links, follow it, or edit its comments. Send only the fields to change. null clears a field. tags, linked_items and involved_people replace the whole list; add_links and attach_file_ids keep what is there. When to use - The user wants to move, reassign, reschedule, complete, archive or follow a task, or add files or links. When NOT to use - To post a new comment. Call add_task_comment.
