Wordsmith

View saved version →

---
name: contract-review
description: Review a contract in Wordsmith against one of the organisation's playbooks or against checks built from the user's instructions, read the findings, and produce a tracked-changes redline. Use when the user asks to review, check or mark up a contract, NDA, agreement or other legal document with Wordsmith.
---

# Contract review with Wordsmith

This workflow takes a contract from the conversation to a reviewed set of findings and a Word redline. A
review runs in Wordsmith for a few minutes, so it starts and finishes in separate tool calls.

## 1. Get the contract into Wordsmith

Every Wordsmith tool works on a Wordsmith file id.

- **An attachment in the conversation, a public https link, or text:** call `add_file`. Set exactly one of
  `file`, `url` or `text`. It returns the file's `id`.
- **A file on the user's machine, when the host can run shell commands:** call `create_file_upload` with
  `file_name`, `content_type` and `content_length`. Run the `curl_command` it returns, with `<path>`
  replaced by the file's path. Then call `complete_file_upload` with the `upload_id` to get the file's `id`.

A review accepts DOCX and PDF files, up to 10 reviewed together.

## 2. Choose what to review against

- **A playbook:** the organisation's saved positions for a contract type. Call
  `find_resources` with `kind="playbook"` and a `query` such as `"NDA"` to find its id.
- **Instructions:** if no playbook fits, the review builds its checks from written instructions, such as
  "check the limitation of liability, governing law and termination for convenience".

Note which side the user acts for, as the document names it (for example "the Supplier"). The review
reads the contract from that party's position.

## 3. Start the review

Call `review_document` with:

- `type`: `"playbook"` with `playbook_id`, or `"instructions"` with `instructions`
- `file_ids`: the ids from step 1
- `party`: the side the user acts for

The call waits up to `wait_seconds` (at most 20). If the result has an `operation_id` and a running status,
call `get_operation` with it until the status is final. The finished result carries the `review_id`.

## 4. Read the findings

Call `get_review` with the `review_id`. It returns the review's status, its finding counts, the
`redline_file_id` of the full redline, and a page of findings. Each finding has an explanation, the cited
contract text and any proposed amendment.

- `finding_status` defaults to `"issue"`. Use `"all"` to include passed checks.
- `severity` filters issues to `"major"`, `"minor"` or `"info"`, the words the Wordsmith app uses.
- Pass the returned `cursor` to read the next page.

## 5. Produce a redline

The review's own redline, with every proposed amendment, is the `redline_file_id` from `get_review`.

For a redline with only some amendments, call `update_review` with `action="generate_redline"`, the
`review_id` and the chosen `finding_ids`. It returns a new `file_id`: a tracked-changes DOCX, or a ZIP of
DOCX files when the review covered several documents. If it returns an `operation_id`, finish it with
`get_operation`.

To give the user the document, call `read_file` with the file id and `include=["download_url"]`. The link
works without sign-in and expires after 5 minutes.

## Example

A user attaches a supplier's NDA and asks for a review against the company NDA playbook, acting for the
customer:

1. `add_file(file=<attachment>)` returns `id: "f_123"`.
2. `find_resources(kind="playbook", query="NDA")` returns the playbook `pb_456`.
3. `review_document(type="playbook", playbook_id="pb_456", file_ids=["f_123"], party="the Customer")`
   returns an `operation_id`; `get_operation` returns `review_id: "rv_789"`.
4. `get_review(review_id="rv_789", severity="major")` lists the major issues.
5. `update_review(review_id="rv_789", action="generate_redline", finding_ids=[...])` returns the
   redline's `file_id`.

View saved version →

---
name: draft-from-blueprint
description: Draft a Word or PDF document in Wordsmith from one of the organisation's blueprints (document templates with placeholders), filling the placeholders from known values, source documents or a past conversation. Also drafts a new document from instructions when no blueprint fits. Use when the user asks to draft, prepare or generate an agreement, letter or other document with Wordsmith.
---

# Drafting from a blueprint with Wordsmith

A blueprint is a Wordsmith document template with placeholders, such as the party names, the effective date
or the governing law. Wordsmith's `draft_document` tool fills a blueprint, or drafts a new document from
instructions when there is no blueprint.

## 1. Find the blueprint

Call `find_resources` with `kind="blueprint"` and a `query`, such as `"mutual NDA"`. To see a blueprint's
placeholders and their keys, call `get_resource` with `kind="blueprint"` and its id.

## 2. Gather the inputs

`draft_document` fills placeholders from any mix of these:

- `values`: the placeholder values already known, keyed by placeholder key
- `context`: facts to draft from, up to 20,000 characters
- `file_ids`: source documents, such as a term sheet. Add them with `add_file` first
- `session_id`: a past Wordsmith conversation to draft from. Find one with `find_resources(kind="session")`

When `values` covers every required placeholder, Wordsmith fills the blueprint from them alone. Otherwise
it drafts the missing values from the context, files or session.

## 3. Draft

Call `draft_document` with `blueprint_id` and the inputs above. Optional: `file_name` (without extension)
and `output_format` (`"docx"` by default, or `"pdf"`).

Without a blueprint, pass `instructions` describing the document, plus any `context` or `file_ids`.

The call waits up to `wait_seconds` (at most 20). If it returns an `operation_id`, call `get_operation`
until the status is final.

## 4. Check and share the draft

The result holds:

- `file_id`: the new document. `read_file` with `include=["text"]` returns its text, and with
  `include=["download_url"]` a link that expires after 5 minutes
- the `values` Wordsmith used for each placeholder, including the ones it drafted, for the user to check
- `url`: opens the draft in Wordsmith

## Example

A user asks for a mutual NDA with a named counterparty, starting today, from the term sheet they attached:

1. `find_resources(kind="blueprint", query="mutual NDA")` returns `bp_12`.
2. `add_file(file=<term sheet>)` returns `f_34`.
3. `draft_document(blueprint_id="bp_12", values={"counterparty_name": "Example Holdings Ltd"}, file_ids=["f_34"])`
   returns an `operation_id`; `get_operation` returns the `file_id`, the `values` used and the `url`.

View saved version →

---
name: file-into-repository
description: Create a Wordsmith repository, organise it into folders, add documents to it so they become searchable, and remove a document. Use when the user asks to file, store or organise contracts and other documents in Wordsmith, or to set up a repository for a matter or contract type.
---

# Filing documents into a Wordsmith repository

A repository is a searchable collection of an organisation's documents in Wordsmith, such as executed
contracts or precedents. Wordsmith's `manage_repository` tool creates repositories and folders and adds and
removes documents. Wordsmith's `search_knowledge` tool then searches what is filed.

## 1. Find or create the repository

- **An existing one:** call `find_resources` with `kind="repository"` and a `query`. `get_resource` with
  `kind="repository"` and `include=["folders"]` or `include=["documents"]` lists its contents.
- **A new one:** call `manage_repository` with `action="create"`, a `name` and optionally a `description`.
  It returns the `repository_id`.

To organise documents, call `manage_repository` with `action="create_folder"`, the `repository_id`, a
`name`, and a `parent_id` for a folder inside another folder.

## 2. Get the documents into Wordsmith

Each document needs a Wordsmith file id. Call `add_file` for an attachment, a public https link or text.
For a file on the user's machine, call `create_file_upload`, run its `curl_command`, then call
`complete_file_upload`.

## 3. Add them to the repository

Call `manage_repository` with `action="add_files"`, the `repository_id`, up to 100 `file_ids`, and an
optional `folder_id`. Each file moves into the repository and becomes a searchable document.

Indexing runs in the background. If the result has an `operation_id`, call `get_operation` until the
`repository_indexing` operation finishes. The documents are searchable after that.

## 4. Search what is filed

Call `search_knowledge` with a `query` and the `repository_ids` to search. Each passage it returns carries
the `document_id`, the `file_id` and a relevance score. `read_file` with the `file_id` and
`include=["text"]` returns the document's text a page at a time.

## Removing a document

`manage_repository` with `action="remove_document"` takes the repository's `document_id`, not the
`file_id`, and deletes both the document and its file. This tool cannot delete a whole
repository.

## Example

A user attaches three signed supply agreements and asks to file them under a new "Supply agreements"
repository, in a "2026" folder:

1. `manage_repository(action="create", name="Supply agreements")` returns `repo_1`.
2. `manage_repository(action="create_folder", repository_id="repo_1", name="2026")` returns `fld_2`.
3. `add_file` for each attachment returns `f_a`, `f_b` and `f_c`.
4. `manage_repository(action="add_files", repository_id="repo_1", folder_id="fld_2", file_ids=["f_a", "f_b", "f_c"])`
   returns an `operation_id`; `get_operation` reports when indexing is done.

View saved version →

---
name: legal-research
description: Search case law and legislation in public legal databases through Wordsmith, and read the full text of a judgment, statute or regulation. Use when the user asks for cases, statutes, regulations or EU law on a legal point, or for the text of a specific judgment or Act.
---

# Legal research with Wordsmith

Wordsmith's `legal_research` tool searches several public legal sources at once and reads documents from
them. It finds and reads primary sources. For a researched answer or memo, Wordsmith's `ask_wordsmith`
tool hands the question to a Wordsmith agent instead.

## Sources

| Source | Covers |
| --- | --- |
| `moonlit` | Legislation in 30+ jurisdictions, strongest in civil-law Europe |
| `courtlistener` | US case law |
| `uk_case_law` | UK judgments |
| `uk_legislation` | UK Acts and statutory instruments |
| `nz_legislation` | New Zealand legislation |
| `eur_lex` | EU law and CJEU judgments |
| `federal_register`, `regulations_gov` | US federal rules and rulemaking |
| `sec_edgar` | US SEC filings (search only) |

## 1. Search

Call `legal_research` with `action="search"` and a `query` in plain language or as a citation, such as
`"[2015] UKSC 72"`. Narrow it with:

- `jurisdictions`: lower-case ISO country codes plus `"eu"`, for example `["gb"]`
- `sources`: a subset of the sources above. The default searches every source the user can use
- `date_from` and `date_to`: `YYYY-MM-DD`
- `limit`: up to 50 results

The result lists matches from every source, each with a `source` and `document_id`. It also reports each
source's status. `timeout` means that source was slow and returned nothing. `partial` means some of its
matches may be missing, so a repeat search with only that source can fill the gap.

## 2. Read a document

Call `legal_research` with `action="read"`, the result's `source` and `document_id`. `max_chars` sets how
much text comes back (default 20,000). A non-null `next_offset` means there is more: call again with
`offset=next_offset`.

`sec_edgar` results cannot be read. Their `url` opens the filing on the SEC's site.

## Example

A user asks for the leading UK authority on the penalty rule in liquidated damages clauses:

1. `legal_research(action="search", query="penalty rule liquidated damages legitimate interest", jurisdictions=["gb"], sources=["uk_case_law"])`
2. The results include *Cavendish Square Holding BV v Makdessi* `[2015] UKSC 67`.
3. `legal_research(action="read", source="uk_case_law", document_id=<its document_id>)` returns the
   judgment text, with `next_offset` for the next part.