# Tools

> The twelve Copyleaks tools an agent can call, and the parameters each one takes.

Twelve tools, grouped by the job they do.

## Scanning

<AccordionGroup>

<Accordion title="copyleaks_scan - Run a Copyleaks scan" icon="magnifying-glass">
  *Write · spends credits*

  Runs a scan and returns a handle to check on. Accepts pasted text, a web address, files, or an uploaded image.

  | Parameter | What it takes |
  |---|---|
  | `scan.text` | Text to scan, pasted directly. Capped at **25,000 characters** - send longer content as a file, which has no character ceiling |
  | `scan.urls` | Web addresses, **up to ten per call** - the same spend guard as `files`. Each is fetched by Copyleaks itself, without your sign-ins |
  | `scan.files` | Files to scan, each with its name and extension - `thesis.pdf`. **Up to ten per call** - a deliberate guard so one mistaken instruction cannot spend a large share of the balance. Send the rest as a second call |
  | `scan.files[].size` | **Required when sending file content:** size in bytes before encoding. Checked against what arrived; a mismatch is refused rather than scanned |
  | `scan.image` | The handle for an uploaded image, from `copyleaks_request_upload` |
  | `scan.name` | What to call this scan in your Copyleaks account |
  | `scan.profile` | The scan profile to use. Omit for your default |
  | `detectors` | What to run on text: `AI Detection`, `Plagiarism Detection`, or both. Ignored for an image scan |

  `detectors` is what you ask Copyleaks to use. `detections` in the results is what actually ran - they differ when, for example, text falls under the 350-word AI minimum.

  Returns immediately with a scan that is still running. Follow with `copyleaks_scan_status`, then `copyleaks_get_results`.
</Accordion>

<Accordion title="copyleaks_rescan - Re-run an existing scan" icon="arrows-rotate">
  *Write · spends credits*

  Runs an existing scan again against current sources, so a document can be re-checked as the web changes. Creates a new scan; the original and its results are unchanged.
</Accordion>

<Accordion title="copyleaks_request_upload - Get a place to send a file" icon="upload">
  *Write · costs no credits*

  Returns an address to send one file to, and a handle that names that file in a later scan. Use it for anything past a small file, rather than sending bytes inside `copyleaks_scan`.

  | Parameter | What it takes |
  |---|---|
  | `file_name` | The file's name including its extension. The extension decides which formats are accepted |
  | `size` | The file's size in bytes, checked against the upload limit before anything is sent |

  Send the file to the address, then start the scan with the handle. **The address works once** and also expires after a set time; the handle starts one scan. If either has been spent, ask for another. A failed upload does not spend the address.
</Accordion>

</AccordionGroup>

## Reading results

<AccordionGroup>

<Accordion title="copyleaks_scan_status - Check scan status" icon="hourglass-half">
  *Read-only*

  Returns whether a scan is `running`, `complete`, or `failed`. While running, may include how far along it is as a percentage.

  **No time estimate is available** - a percentage says how far along the scan is, not how long remains. There is no notification when a scan finishes; checking here is the only way to find out. Checking again before anything has changed returns the same answer, so wait between checks.
</Accordion>

<Accordion title="copyleaks_get_results - Get scan results" icon="list-check">
  *Read-only*

  Returns a completed scan's scores, counts, sources, and matched text.

  | Parameter | What it takes |
  |---|---|
  | `scan` | The scan to read |
  | `detail` | `scores`, `summary` *(default)*, `detail`, or `full`. See [Results](/mcp/results) |
  | `match_types` | `Exact match`, `Minor changes`, `Paraphrased` |
  | `source_types` | `Web`, `Shared data hub`, `Private cloud hub`, `This Batch` |
  | `source` | Narrow to one matched source, by title |
  | `min_matched_words` | Sources with at least this many matched words |
  | `published_after` / `published_before` | ISO 8601 dates. Sources with no known publish date are kept unless `include_undated` is `false` |
  | `include_undated` | Keep undated sources when filtering by date. `true` by default |
  | `exclude_domains` | Domains to leave out |
  | `tags` | Only sources carrying these tags |
  | `with_alerts_only` | Only results the report raised an alert on |
  | `ai_source_match_only` | Only sources carrying the `AI Source Match` tag |
  | `shared_hub_scope` | For `Shared data hub` sources: `mine`, `others`, or both |
  | `min_phrase_frequency` | Only AI phrases at or above this frequency |
  | `page` | Which page to return |
  | `pageBytes` | How much one page may return, measured in UTF-8 bytes. Defaults to **9,000**; raise up to **500,000** if your client can hold more. **A page always carries at least one result**, so a single very long match arrives on its own rather than not at all |
</Accordion>

<Accordion title="copyleaks_get_flagged_segments - List flagged segments in document order" icon="list-ol">
  *Read-only*

  Returns every flagged part of a document **in the order it appears**, rather than grouped under the sources they matched. Use this to go through a document start to finish; use `copyleaks_get_results` to ask about a particular source.

  Each segment carries its exact text, its type (`Exact match`, `Minor changes`, `Paraphrased`, **AI content**, or **AI phrases**), and - for a match - which source it overlaps and what that source says.

  | Parameter | What it takes |
  |---|---|
  | `scan` | The scan to walk through |
  | `page` | The `nextPage` value from a previous response. Omit for the first page |
  | `pageBytes` | As above - UTF-8 bytes, 9,000 default, 500,000 max, always at least one segment per page |
</Accordion>

</AccordionGroup>

## Past scans

<AccordionGroup>

<Accordion title="copyleaks_search_scans - Search past scans" icon="magnifying-glass-chart">
  *Read-only*

  Searches the scans you own. Use it to find a scan you are describing rather than naming - *"the one from June that scored over 30%."*

  | Parameter | What it takes |
  |---|---|
  | `query` | Free text matched against the scan's title |
  | `status` | `running`, `complete`, or `failed` |
  | `detection` | What Copyleaks looked for: `AI Detection` or `Plagiarism Detection` |
  | `submitted_as` | What you handed over: `file`, `text`, `url`, or `image` |
  | `created_after` / `created_before` | ISO 8601 dates |
  | `min_ai_score` / `max_ai_score` | Narrow by `AI score`, 0-100 |
  | `min_plagiarism_score` / `max_plagiarism_score` | Narrow by `Plagiarism score`, 0-100 |
  | `folder` | The folder's name, as you see it in Copyleaks |
  | `sort` | How to order results |
  | `page` / `limit` | Which page, and how many per page |

  **`detection` and `submitted_as` answer different questions.** *"Find my AI scans"* is `detection`. *"Find the PDFs I scanned"* is `submitted_as`.

  <Warning>
    **Older listing rows carry a whole-number score** - `23` where the scan itself holds `23.1`, truncated rather than rounded. Rows recorded more recently carry the decimal. Where the exact figure matters, read the scan with `copyleaks_get_scan` or `copyleaks_get_results`.
  </Warning>

  A row also carries `totalWords`, which is what separates *a detector ran and found nothing* from *it never ran* - `AI Detection` does not run below 350 words, so a `0` without a word count means either. Rows recorded before this was stored report it as null.
</Accordion>

<Accordion title="copyleaks_get_scan - Get one scan" icon="file-lines">
  *Read-only*

  Returns one scan's title, date, type, score, and status. Use `copyleaks_get_results` for what it found.
</Accordion>

</AccordionGroup>

## Scan profiles

<AccordionGroup>

<Accordion title="copyleaks_get_profiles - Get scan profiles" icon="sliders">
  *Read-only*

  Returns your scan profiles and their settings. A scan profile is a saved set of scan settings you reuse by name - the same profiles you see in Copyleaks Scan Settings.
</Accordion>

<Accordion title="copyleaks_create_profile - Create a scan profile" icon="plus">
  *Write*

  Creates a new profile from settings described in plain language, and returns what was saved. Setting names are the app's own:

  | Group | Settings |
  |---|---|
  | `AI Detection` | `Sensitivity level`: `Cautious` · `Balanced` (default) · `Broad` |
  | `Search sources` | `Web search` (`Entire web` / `Specific sites only` / `Exclude specific sites`) · `Shared data hub` · `Private cloud hub` · `Cross-check documents` |
  | `Match settings` | `Match scope`: `Exact match` (always on) · `Minor changes` · `Paraphrased`. `Scan mode`: `Originality check` with `Performance mode` (`Quick scan` / `Standard` / `Comprehensive`), or `Copyright check` |
  | `Cross-language search` | Each added language runs as a separate scan and multiplies the credit cost |
  | `Security & Integrity` | `Safe Search` · `Mask Personal Data` · `Cheat Detection` |
  | `Exclusions` | References & bibliography · Direct quotes · Citations · Table of Contents · Section headings · Page header and footer · Code comments |

  If a setting is not included on your account, it is left out, the rest of the profile is saved, and you are told which setting and whether it is an add-on or part of a plan.

  Creating a profile never changes which profile is your account default.
</Accordion>

<Accordion title="copyleaks_update_profile - Update a scan profile" icon="pen">
  *Write*

  Changes named settings on an existing profile. Settings you do not name are left as they are. Returns the full profile as saved.
</Accordion>

</AccordionGroup>

## Account

<AccordionGroup>

<Accordion title="copyleaks_get_account - Get plan and credit balance" icon="wallet">
  *Read-only*

  Returns your credit balance, your plan, and which settings this account does not include - each marked as an add-on or as part of a plan.

  **This is the only place credits appear.** Buying credits and changing plans are done in your Copyleaks account, not through this connector.
</Accordion>

</AccordionGroup>