---
title: "Tools and controls"
description: "What the agent runs on the server, the per-request controls that narrow it, structured JSON output, plan entitlements, and rate limits."
canonical_url: "https://scholarxiv.com/developers/docs/agent-api/tools"
markdown_url: "https://scholarxiv.com/developers/docs/agent-api/tools.md"
---

> For the complete documentation index, see [llms.txt](/llms.txt).

# Tools and controls
URL: /developers/docs/agent-api/tools
LLM index: /llms.txt
Description: What the agent runs on the server, the per-request controls that narrow it, structured JSON output, plan entitlements, and rate limits.
Related: agent-api, agent-api/runs, papers-api/limits, mcp/tools, router-api/completions

# Tools and controls

## The tools

The server selects the same tool set as `/chat`, including paper and web research, federated sources, selected context, and supported research workflows. Full-text reading, code execution, and other paid capabilities follow the caller's live entitlements. A client need not implement these tools; richer outputs may need its own UI or a link to the website.

Each tool appears as a `tool-{name}` part in `message.parts` and in stream events. A tool the plan does not include is left out of the turn entirely, so the agent never plans around it. The plans below are the defaults; an account's live entitlements decide.

| Tool                                                                                                                                                                                  | What it does                                                                              | Plan                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------- |
| `searchResearchPapers`                                                                                                                                                                | Searches 3M+ arXiv papers.                                                                | All                                 |
| `webSearch`                                                                                                                                                                           | Searches the web for sources outside arXiv.                                               | All                                 |
| `getSelectedPapers`, `getSelectedTexts`                                                                                                                                               | Read the `selected_papers` and `selected_texts` you sent.                                 | All                                 |
| `searchFederatedResearch`                                                                                                                                                             | Searches arXiv, OpenAlex, Semantic Scholar, Crossref, PubMed and the other sources.       | Go and up (federated search)        |
| `readPaperContent`                                                                                                                                                                    | Reads a paper's full text, a section at a time.                                           | Plus and up (code sandbox)          |
| `executePython`                                                                                                                                                                       | Runs Python in the [code sandbox](#the-code-sandbox).                                     | Plus and up (code sandbox)          |
| `openResearchHub`, `createLatexProject`, `readLatexFiles`, `editLatexFile`, `addFigureToLatexProject`, `peerReviewLatexProject`, `prepareJournalSubmission`, `publishJournalPreprint` | The research-to-manuscript workflow in Write and the Journal.                             | Plus and up (code sandbox)          |
| `generateResearchFigure`                                                                                                                                                              | Generates a figure image.                                                                 | Plus and up (also figure generator) |
| `compileLatexProject`                                                                                                                                                                 | Builds a Write manuscript into a PDF.                                                     | Plus and up (also LaTeX compile)    |
| `voiceMemo`                                                                                                                                                                           | Records a short spoken summary.                                                           | Plus and up (voice)                 |
| `save_memory`, `retrieve_memories`, `edit_memory`, `delete_memory`, `clear_memories`                                                                                                  | The account's saved memories. Off with `tools.memory: false` or the memory setting.       | All                                 |
| `connectAccount` and connected-service tools                                                                                                                                          | Mail, calendars, drives and other connected accounts. Off with `tools.connectors: false`. | All, once an account is connected   |

The [Health Chat API](/developers/docs/health-api) runs its own tools: `searchMedicalLiterature`, `resolveMedications`, `getMedicationReference` and `getDrugLabelInteractions`, plus the memory tools.

### Files and errors

Every tool that makes a file saves it as an upload and lists it in the response's [`files`](/developers/docs/agent-api/files#files-the-agent-makes): `generateResearchFigure`, `executePython` (plots and written files), `compileLatexProject` (the built PDF) and `voiceMemo`. The website shows them from the tool output, and the agent is told not to link or embed them. If an answer still mentions `attachment://<id>`, it means one of those files.

A tool that fails does not fail the turn: the agent sees the error and carries on. In `message.parts`, a failure is either a part with `state: "output-error"` and `errorText`, or an `output` with an `error` field. Check both.

## The code sandbox

On Plus and Pro the agent can run Python (`executePython`) in a fresh, isolated Jupyter sandbox. Ask for a chart, a calculation, or a file ("plot this and send me the CSV") and it writes and runs the code itself. Every run is summarised in `sandbox`. That is `sandbox` in the JSON response, and `result.sandbox` on a run:

```json
{
	"sandbox": [
		{
			"tool_call_id": "call_1",
			"status": "completed",
			"code": "import matplotlib.pyplot as plt\n…\nplt.savefig('chart.png')",
			"stdout": "saved chart.png\n",
			"stderr": "",
			"text": null,
			"error": null,
			"outputs": [],
			"figures": [
				{
					"attachment_id": "6ae2…",
					"mime": "image/png",
					"download": "/api/v1/uploads/6ae2…",
					"content": "/api/v1/uploads/6ae2…/content"
				}
			],
			"files": [
				{
					"filename": "chart.png",
					"path": "/home/user/chart.png",
					"size": 48211,
					"attachment_id": "6ae3…",
					"mime": "image/png",
					"download": "/api/v1/uploads/6ae3…",
					"content": "/api/v1/uploads/6ae3…/content",
					"skipped": null
				}
			]
		}
	]
}
```

| Field              | What it holds                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| `status`           | `completed`, `error` (the code raised, or the sandbox failed), or `running` while streaming.                |
| `code`             | The Python that ran.                                                                                        |
| `stdout`, `stderr` | Everything the code printed.                                                                                |
| `text`, `outputs`  | The cell's value as Jupyter prints it, and any other non-image results (text, Markdown, chart specs, data). |
| `error`            | `name`, `value` and `traceback` of the exception, or `null`.                                                |
| `figures`          | Plots the code displayed, such as `plt.show()`.                                                             |
| `files`            | Files the code wrote under its working directory, `/home/user`, kept after the sandbox is discarded.        |

To get a file back, ask for it: "write the script to `analysis.py` and send it", "save the cleaned table as an Excel file". The agent writes it to disk in the code, and it comes back in `files`.

| Kind                 | Kept as                                                                                                                                                                                                                                                                                              |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Images and video     | PNG, JPEG, GIF, WebP, MP4, WebM, with their own `mime`.                                                                                                                                                                                                                                              |
| Documents and data   | PDF, CSV, TXT, Markdown, DOCX, XLSX, PPTX and ZIP, with their own `mime`.                                                                                                                                                                                                                            |
| Source and text data | `.py`, `.ipynb`, `.r`, `.sql`, `.sh`, `.js`, `.ts`, `.html`, `.css`, `.svg`, `.xml`, `.json`, `.jsonl`, `.yaml`, `.toml`, `.tsv`, `.log`, `.tex`, `.bib`, most other source extensions, and `Dockerfile`, `Makefile` and `requirements`. `mime` is `text/plain`; `filename` keeps the original name. |

Each file can be up to 20 MB, at most 10 are kept per run, and they count toward the account's storage. Opaque binaries such as `.pkl`, `.npy` or `.bin` are not kept; ask the agent to zip them. A file that is not kept is still listed, with `skipped` set to `unsupported_type`, `too_large`, `too_many_files`, `storage_limit` or `save_failed`. Download figures and files as described in [Files the agent makes](/developers/docs/agent-api/files#files-the-agent-makes). Every one also appears in the response's `files`.

Source files are stored as `text/plain` so nothing renders them: an `.html` or `.svg` file comes back as its source. Save it with its `filename` to use it.

While streaming, the same data arrives in the `tool-output-available` event for `executePython` (`output.logs`, `output.results`, `output.artifacts`, `output.error`).

## Per-request controls

These fields shape one turn. None of them can add a tool, model, or budget the plan does not already allow.

| Field                       | Effect                                                                                                                          |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `tools.allow`               | Only these tools may run (after plan gating).                                                                                   |
| `tools.deny`                | These tools may not run.                                                                                                        |
| `tools.memory`              | `false` removes the memory tools and keeps saved memories out of the prompt.                                                    |
| `tools.connectors`          | `false` removes connected-account tools (mail, calendars, drives).                                                              |
| `tools.custom_instructions` | `false` leaves the account's custom instructions out of this turn.                                                              |
| `max_steps`                 | 1–10. Lowers the tool-step budget for this turn. When the budget is spent the agent writes its answer from the evidence it has. |
| `metadata`                  | Up to 16 string tags, returned on the run and counted in [usage](/developers/docs/agent-api/usage).                             |

```json
{
	"message": "Find three recent papers on sparse attention",
	"tools": { "allow": ["searchResearchPapers", "readPaperContent"], "memory": false },
	"max_steps": 3,
	"metadata": { "customer": "acme", "ticket": "T-1042" }
}
```

## Structured output

Ask for a JSON object alongside the prose answer:

```json
{
	"message": "Is there evidence that intermittent fasting improves insulin sensitivity?",
	"response_format": {
		"type": "json_schema",
		"json_schema": {
			"name": "evidence_summary",
			"description": "A verdict for a dashboard card",
			"schema": {
				"type": "object",
				"properties": {
					"verdict": { "type": "string", "enum": ["supported", "mixed", "unsupported"] },
					"key_papers": { "type": "array", "items": { "type": "string" } }
				},
				"required": ["verdict", "key_papers"]
			}
		}
	}
}
```

The agent researches and answers exactly as it would otherwise. When the answer is complete, it is converted into an object matching your schema, using only what the answer states. The object is returned as `output` in the JSON response and in `result.output` on the run, and streamed as a `data-output` event just before `finish`. If conversion fails the turn still succeeds, with `output: null` and an `output_error`. The schema root must be `type: "object"` and serialize to at most 32,000 characters; `name` is 1–64 letters, digits, `_` or `-`. `{ "type": "text" }` is the default.

## Entitlements

Tools, models, and deep research resolve live against the API key owner's plan on every request:

- `model: "auto"` picks only from models the plan can reach.
- `deep_research` requires Plus or Pro.
- Attachment and per-chat limits follow the plan too.

Calls use the existing [API rate limits](/developers/docs/papers-api/limits). The hourly window is shared across all of your keys and rolls continuously, so a 429 carries a `Retry-After` header. Reading, streaming and cancelling runs do not count against it.

## What it does not do

The agent is the product, not a thin wrapper: there is no prompt for you to write and no tool loop for you to orchestrate, and you cannot define your own tools. Long work runs as a durable [run](/developers/docs/agent-api/runs) that you can start in the background, resume, and retry safely.

The MCP `research_chat` tool invokes this same service and accepts the same controls (`allowed_tools`, `disallowed_tools`, `max_steps`, `response_schema`, `metadata`, `background`).

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).
