Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions src/content/docs/agents/tools.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -248,6 +248,14 @@ Some larger writes first return a preview and an opaque `plan` value. Review the
- **Endpoints.** Upload uses `PUT /api/uploads/{token}` with the file as the raw request body. Download uses `GET /api/downloads/{token}`. These endpoints need no authentication, because the token in the path is their credential. They need no cookie, bearer token, or `X-ShipLean-Client` header. Unknown, expired, or spent tokens return 404 as invalid links. Tokens that a disabled user or a revoked agent authorization invalidated also return 404. Download links return 404 when the attachment has been archived or replaced. ShipLean checks project membership separately, through normal project access. If an upload is too large, or the item has no room left for attachments, the upload fails and nothing is stored.
- **Reverse proxies.** Configure the proxy to bypass login and identity injection for `/api/uploads/` and `/api/downloads/`, as it does for other endpoints that have their own credentials. Generated absolute URLs use the configured instance base URL when one is set. If it is blank, ShipLean takes the origin from the last `X-Forwarded-Host` and `X-Forwarded-Proto` values, when the request came from a trusted peer. It ignores cluster service names, such as `*.svc` and `*.svc.cluster.local`. Otherwise, it uses the request host and scheme. Configure the trusted proxy to forward the public host and scheme, so agents can reach the returned URLs. See [sign-in proxy paths](/start/sign-in/#keep-the-backend-private) and the [proxy examples](https://github.com/ShipLean/docs/tree/main/examples/proxy).

## Tool result contents

Every completed tool call, including errors, returns text blocks in `content`: a short summary first, a Markdown representation for `get_brief` and `planning_guide` when applicable, and a JSON representation last. The same JSON object is also available in `structuredContent`.

For example, a preview's `plan` token or a work item's key is in the JSON block even when the summary mentions only the next action. Clients that expose only `content` can read the complete result there; clients that expose both fields may display duplicate information. If an agent sees only the summary because its client hides or truncates the other blocks, it should tell the person that the tool response is incomplete, not search for or guess the missing output. The complete JSON must be available before applying a preview that requires a `plan` token.

Tool errors follow the same content layout and carry `isError: true` with an error object in `structuredContent`. HTTP authorization failures such as a missing scope are separate from tool results.

## Request limits and errors

The `/mcp` body cap is `4 × ceil(file_limit / 3) + 64 KiB`. It fits one base64-encoded attachment and the JSON-RPC envelope. With the default 25 MiB file limit, the cap is **35,018,072 bytes**, which is about **33.4 MiB**. Kestrel's usual 30,000,000-byte request limit is raised for `/mcp` to match. A base64 `attach_file` can include a file up to the configured per-file attachment limit. The 200 KB limit for reading Markdown inline has not changed. Larger Markdown returns metadata and a short-lived download URL.
Expand Down
Loading