An MCP server that gives Claude Code read/write access to claude.ai / Cowork projects, their knowledge documents and uploaded files, and their scheduled tasks.
Projects: list, get (with instructions), create, update (name/description/instructions), and delete a project with everything in it.
Documents: list (with knowledge capacity and duplicate-name flags), read, write/replace, rename, and delete text documents, each backed up locally before it is touched.
Uploaded files: see which PDFs and images count toward knowledge, pull them down as bytes, and push PDF/PNG/JPEG/GIF/WebP files up as uploads.
Bulk transfer: copy a whole project's documents and uploads into a local folder and push a folder back in, with dry-run preview, skip-unchanged, overwrite control, and no remote deletions.
Scheduled tasks: list (per project or account-wide), get, create with a UTC cron schedule or manual-only, update/pause, and delete.
Capacity enforcement: refuse writes that would cross a project's search threshold or maximum knowledge size, name the best compaction candidates, and allow allow_search_mode only for the threshold.
Safety: explicit overwrite, expected_uuid optimistic locking, local pre-write backups, exact-name confirmation for project deletion, and warnings relayed verbatim to the user.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claude-projects-mcp-server list my projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives Claude Code read and write access to Claude Cowork / claude.ai projects, the knowledge documents ("Context" files) inside them, and the scheduled tasks that run against them.
Cowork keeps a team's shared documents inside the web UI, where Claude Code cannot see them. This server closes that gap, so notes written in Cowork can be read, edited, and written back from the terminal — and the projects that hold them can be created, renamed, and retired without leaving the editor.
Unofficial. This uses the same undocumented endpoints the claude.ai browser app uses, authenticated with a
sessionKeycookie. Anthropic can change or break them without notice. Endpoint shapes were derived from guidodinello/claude-client.
All seventeen tools are implemented and covered by 572 tests, and the read-and-write path for text documents, projects, and scheduled tasks has been verified against the real API — tests/live/test_contract.py round-trips a document through create, read, replace, and delete, a project through create, read, update, and delete, and a scheduled task through create, read, schedule, pause, and delete.
Files uploaded through the web UI, such as PDFs, are listed, pulled, pushed, and backed up before a deletion; the listing and pull_documents have run against real PDFs and the upload request against a real PNG, but removing an upload and the pre-delete backup of uploads have only run against the in-memory fake (see To do).
That live suite also checks the derived chat_project_id against what claude.ai really sends, which is the one thing the offline tests cannot prove: there, both sides of the comparison come from this repository's own encoder.
What that established, and what the implementation now relies on:
A Cowork project is a classic claude.ai project, at /organizations/{organization}/projects/{uuid}.
There is no separate Cowork API surface.
Organization and document listings are bare JSON arrays with no pagination envelope.
Projects are listed through projects_v2, which wraps its rows in {data, pagination}.
That envelope is the reason for preferring it: a bare array cannot distinguish "that is all of them" from "that is the first thirty", so a truncated answer would be indistinguishable from a complete one.
The client walks every page.
Document listings include content, so reading costs one request rather than two.
Two documents may share a file_name, which is what lets a save create the replacement before deleting the original rather than the other way round.
Projects have no such limitation: PUT takes a partial body, so an update touches only the fields it is given.
Project instructions (prompt_template) come back only from a single-project fetch — never from a listing or a create response, which is why get_project exists separately.
Scheduled tasks (observed 2026-08-08) sit at /organizations/{organization}/cowork/scheduled_tasks and behave unlike anything else here:
They are organization-scoped, not project-scoped, and the listing ignores every query parameter it is given — three spellings of a project filter returned byte-identical bodies. Narrowing to one project happens client-side.
A task names its project as a chat_project_id (claude_proj_01…) and never as a uuid, though it is created with a project_uuid. The two are the same value in different clothes: claude_proj_01 followed by the uuid in base58, left-padded to 22 characters. identifiers.py is that mapping, and it is the one piece of this server that reimplements somebody else's encoding rather than reading a field.
Schedules are cron expressions in UTC. The web UI's Manual / Hourly / Daily / Weekdays / Weekly menu is presentation: choosing Weekly, Monday, 09:00 in a UTC+9 browser sends 0 0 * * 1. A task with no schedule omits the field rather than carrying an empty one.
enabled is absent when false. A paused task has no enabled key at all, so anything defaulting it to true reports every paused task as running.
next_run_at is 0001-01-01T00:00:00Z — Go's zero time — for a task that has no schedule, and carries a few minutes of scheduler jitter otherwise.
The API validates a cron expression (400 on nonsense) but not a model id: an invented one is stored with a 200 and only fails when the task runs. create_scheduled_task warns about a model that does not look like an id rather than refusing, so a model newer than this code still works.
Uploaded files (observed 2026-09-18) sit at /organizations/{organization}/projects/{uuid}/files, a sibling of /docs, and are a different kind of thing from a document:
The listing is a bare JSON array like the others.
Each entry carries file_name, file_kind (document for a PDF), created_at, size_bytes, the same value under uuid and file_uuid, and a document_asset with page_count but a null token_count, so nothing in it can be added up to the knowledge size.
They count toward knowledge_size without appearing in the documents listing.
Found while copying nine projects between two organizations: in eight of them the documents' summed estimated_token_count matched the reported knowledge size exactly, and in the ninth the two Markdown documents summed to 13,757 against 19,641, with two PDF files in the web UI to account for the gap.
That exact match is why list_documents treats a shortfall with no listed upload to explain it as a warning rather than rounding.
document_asset.url is /api/{organization}/files/{file_uuid}/document_pdf: host-relative, outside the project path, and already starting with the /api that the base URL ends with.
The transport resolves it against the origin rather than appending it, refuses any other origin so the session key never travels, reads the body as bytes rather than JSON, and rejects an HTML page served in its place, which is what a stale session gets.
The client then checks the byte count against size_bytes, the one thing the listing says about the file's contents.
Only a document_asset whose file_variant is original counts as the file.
A PDF has one; an image (observed 2026-09-26) has a preview_asset and a thumbnail_asset, which are renditions, and no document_asset key at all, so it is listed but can be neither pulled nor backed up.
That image, 8,929 bytes, accounted for 4 tokens of the knowledge size.
An HTML file and a plain text file added through the web UI's knowledge upload (observed 2026-09-26) became text documents rather than uploads, the HTML one keeping its markup. So only PDFs and images have appeared in a files listing so far.
The web UI adds a file with POST /organizations/{organization}/projects/{uuid}/upload (captured 2026-09-26), as multipart/form-data with one part named file carrying the file name and the file's own content type.
The response is the row the files listing will show for it, plus a highres_copy block (max_px 2576, max_tokens 4784, px_per_token 28, jpeg_quality 75, resized false, for a 1456 by 819 PNG) whose meaning is unknown and which nothing here reads.
The stored name is not always the one sent: Coffeevore (scaled).png was listed as Coffeevore scaled.png.
That one renaming is all that has been seen of the rule, so a push matches exact names rather than guessing at it, and warns when the server kept another name that pushing the file again would add a second upload.
Adding the plain text file was a POST to /docs, the document create endpoint (observed 2026-09-26), so it is the browser that decides which files become documents and which uploads, and the upload endpoint has only been seen taking a PNG.
push_documents decides by the extension the same way, from a fixed table rather than the platform's mime types, which differ between machines: .pdf, .png, .jpg, .jpeg, .gif, and .webp are uploads, and every other file, other image formats included, is a text document.
The web UI removes an upload with POST .../files/delete_many, carrying {"file_uuids": ["<file_uuid>"]} as the body, and gets null back (captured 2026-09-28).
The live suite's first run that day had sent DELETE .../docs/{file_uuid} with a {"docUuid": "<file_uuid>"} body, as a capture from 2026-09-26 had shown, and claude.ai answered 404; which removal that capture was of is not known.
What delete_many answers for a uuid the project no longer holds has not been seen, so a 404 from it counts as a failed delete rather than as one already done.
Response shapes captured from the real API live in tests/fixtures/ and are asserted against by tests/test_fixtures.py, which stops the in-memory fake drifting away from what claude.ai actually sends.
Related MCP server: Axme-code
The pre-delete backup of uploads has not been run against a real upload.
The listing and pull_documents have: on 2026-09-18 the server pulled two real PDFs, with the size check passing and %PDF at the start of each file on disk, and tests/live/test_contract.py has opt-in checks that list a throwaway project's uploads and download the first real one on the account.
delete_project backs an upload up with that same download, but what it adds, refusing an upload with no original or no size and stopping before anything is deleted when a backup fails, has only run against the in-memory fake.
Run the live suite with CLAUDE_PROJECTS_LIVE_TESTS=1 against an account holding a PDF, then delete a throwaway project holding one and check the backup directory, before trusting a deletion with uploads in it.
Pushing an upload has run against the real API once, and removing one has not.
On 2026-09-28 tests/live/test_contract.py added a PNG to a throwaway project: the name came back unchanged, the files listing showed it with the byte count sent, and the knowledge size fetched right after the reply had grown, so the capacity gate can see what an upload costs.
Its removal answered 404 on the route then used, and 0.8.0 read a 404 as "already gone", so a refused upload was reported undone and a replaced one removed while both stayed in the project.
Removal now takes the route the web UI uses and treats a 404 as a failure, but that route has only run against the in-memory fake; run the live suite before trusting a push that replaces or refuses an upload, and add a PDF to that check once one has gone through.
What an upload adds to the knowledge size is measured as the change across the upload, since the API reports no token count for one, and the upload it replaces still counts when the verdict is reached, so a replacement near a line can be refused that would have fit once the old copy was gone.
One run is one observation, so a size that did not move across an upload is still treated as unmeasured rather than as a fit.
Uploads other than PDFs cannot be read.
An image's row offers only a preview and a thumbnail (observed 2026-09-26), neither of which is the file, so pull_documents reports it as an error and delete_project refuses until it is removed in the web UI.
Which other kinds the web UI keeps as uploads, and whether they offer an original, is unknown: an HTML file and a plain text file became text documents instead, so only PDFs and images have been seen in a files listing, and push_documents sends only PDFs and PNG, JPEG, GIF, and WebP images as uploads, refusing any other file that is not UTF-8 text, other image formats included, rather than guessing.
The download path still treats an HTML body as a login page served in place of the file, which nothing observed contradicts.
Whether the files listing truncates is unknown.
It is a bare array like the documents listing, so it cannot say "that is all of them", and delete_project now relies on it before an irreversible delete; a project with many uploads is the case to check.
Everything below runs through uv — uvx ships with it — so install that first:
curl -LsSf https://astral.sh/uv/install.sh | shOther installation methods (Windows, Homebrew, pip) are in uv's installation documentation.
Get the session key from claude.ai in a browser: DevTools → Application → Cookies → sessionKey (starts with sk-ant-sid02-, or sid01- on older accounts).
It expires periodically; when a tool reports a 401, copy a fresh one.
Put it in an env file anywhere (.env.example lists every key the server reads):
CLAUDE_PROJECTS_SESSION_KEY=sk-ant-sid02-...Register with Claude Code straight from this repository — no clone needed:
claude mcp add claude-projects -- uvx --refresh --env-file /path/to/.env --from 'git+https://github.com/Attacktive/claude-projects-mcp-server@main' claude-projects-mcp--refresh makes uv re-resolve main every time the server starts, so relaunching Claude Code picks up whatever has been pushed since — at the cost of a git fetch on each launch, and of needing the network for it.
Without it, uv keeps the commit it first resolved until uv cache clean claude-projects-mcp-server is run.
To move only on releases instead, drop --refresh and pin a tag in place of @main.
uv sync
cp .env.example .env # then fill in CLAUDE_PROJECTS_SESSION_KEY
claude mcp add claude-projects -- uv run --directory /path/to/claude-projects-mcp-server claude-projects-mcpRun this way, the server finds the .env sitting next to the project by itself; --env-file is only needed for the git-URL form, whose install location is an ephemeral virtual environment managed by uv.
Tool | Purpose |
| Projects across every chat-capable organization, each tagged with its organization |
| One project, including its instructions — which a listing does not carry |
| Start a project, optionally private and with instructions |
| Change name, description, or instructions; untouched fields are left alone |
| Remove a project and everything in it; every document and uploaded file is backed up first (see Safety) |
| Documents and uploaded files in a project, reporting knowledge capacity usage and flagging duplicate file names |
| One document by uuid or file name |
| Create, or replace with |
| Move a document to a new file name; a name already in use needs |
| Remove a document (always backed up first) |
| Copy a project's documents and uploaded files into a local folder |
| Send a local folder's files into a project (gated by knowledge capacity): PDF, PNG, JPEG, GIF, and WebP files as uploads, everything else as text documents |
| Scheduled tasks, for one project or the whole account |
| One task, including the prompt it will send |
| Schedule a prompt against a project, or leave it manual-only |
| Change a task, or pause it with |
| Remove a task (not backed up first — see Safety) |
Every tool that acts on a project takes an explicit project_id; only list_projects and create_project are account-wide.
Scheduled tasks are addressed by their own task_id once they exist, so only create_scheduled_task names a project; on list_scheduled_tasks a project_id narrows the listing and omitting it widens the search to the account.
Start with list_projects to find the uuid, or take it from the URL: https://claude.ai/cowork/project/<this-part>.
Give documents a file extension: the web UI picks its renderer by name, so notes displays as plain text where notes.md renders as markdown.
write_document and rename_document warn when a name has none — a bare trailing period counts as none — and suggest the .md form; the write itself still goes ahead.
A result carries a warning key only when there is something to hear, and it comes first.
The model is the only reader a tool result is guaranteed to have, so the tool descriptions and the server instructions tell it to relay any warning to the user verbatim — nothing else in the chain will.
The session key is the only required setting; CLAUDE_PROJECTS_BACKUP_DIRECTORY, CLAUDE_PROJECTS_BASE_URL, and CLAUDE_PROJECTS_IMPERSONATE optionally override where backups land, which host is spoken to, and which browser fingerprint curl_cffi presents.
Which organization owns a project is worked out by searching — one listing per organization per session, cached — so a project is reachable wherever on the account it lives, and nothing can be pointed at the wrong place.
A project's knowledge has two lines:
Search threshold (project_knowledge_search_threshold): past this line, Claude in the web UI retrieves from the knowledge instead of reading all of it, so documents can go unseen.
Maximum capacity (max_knowledge_size): past this line, the web UI refuses further uploads until content is removed or compacted.
The API enforces neither line on writes, so this server enforces them:
A write that would grow the project past a line is undone and refused, naming up to three candidate documents most worth compacting (duplicates first, then by size and age).
Passing allow_search_mode=true accepts crossing the search threshold (with a warning); nothing accepts exceeding the maximum capacity.
list_documents reports current knowledge capacity usage under the knowledge key, and the uploaded files that count toward it under uploaded_files.
Uploaded files are never compaction candidates, because only the web UI can remove one, so a refusal names up to three of them in a sentence of their own, largest first. The files listing reports no token count for an upload, so they are ranked and described by their bytes.
An upload pushed from here is gated the same way, with its cost measured as the change in the knowledge size across the upload, since the API reports no token count for one; a refused upload is deleted again. One the gate could not measure, because the size was not reported or did not move, is kept with a warning saying so rather than reported as checked.
These are shared team documents, and the API has no server-side undo, so:
replacing an existing document requires an explicit overwrite=true
the previous content is written to a local backup directory before any replacement
write_document accepts an expected_uuid to refuse the write if a teammate changed the document since you read it
rename_document re-creates the content under the new name before deleting the original — the API has no rename, so a crash midway leaves the document under both names rather than under none
push_documents never deletes remote documents that are missing locally — it is not a mirror
pull_documents copies a project's uploaded files, such as PDFs, down as bytes, and push_documents sends PDF, PNG, JPEG, GIF, and WebP files up as uploads, so a pull-and-push copy carries everything but images, which offer no original to copy (see To do)
push_documents replaces an existing upload only with overwrite=true, after backing its bytes up, matches it by exact name only, and leaves an uploaded image alone, since an image offers no original to compare against or back up
Scheduled tasks are the deliberate exception to the backup rule.
delete_scheduled_task writes nothing to the backup directory before deleting, because a task is a name, a prompt, and a cron line — config that is cheap to retype — rather than content that cannot be reconstructed.
If you only want a task to stop running, update_scheduled_task with enabled=false pauses it and keeps both the prompt and the schedule, which is nearly always the better move.
Running a task is not exposed at all. The API has an endpoint for it, but starting a billable Claude run is not something a tool call should be able to do by accident; set a schedule and let Cowork run it, or press the button in the web UI.
delete_project is the sharpest tool here, because it takes every document and every uploaded file with it.
It is deliberately awkward: confirm_name must match the project's current name exactly, and every text document and every uploaded file is copied to the backup directory before anything is deleted.
If that copy fails for any of them, or the files listing itself cannot be fetched, the project is left standing.
An upload with no downloadable original blocks the deletion too: an image offers only a preview, which is a rendition rather than the file, so remove it in the web UI first or delete the project there.
The backup directory is not an undo feature.
It captures only what this tool overwrites, it lives on one machine, and it knows nothing about edits made by teammates in the web UI.
One known gap: when an interrupted save has left several documents sharing a name, a replacing write backs up only the newest before removing them all — if a teammate may have edited an older duplicate, check it with read_document first, as its warning suggests.
Do not describe it to the team as a safety net.
CLAUDE_PROJECTS_SESSION_KEY is a full personal claude.ai account credential — it can read every conversation on the account and act as you.
Keep it in .env (git-ignored), never share it, and never deploy a hosted instance that serves several people from one key.
uv run pytest tests/ -v # full suite, no network
CLAUDE_PROJECTS_LIVE_TESTS=1 uv run pytest tests/live -v # real round-trip against claude.ai
uv run ruff check .The live suite creates its throwaway projects in the account's only organization.
On an account in more than one, set CLAUDE_PROJECTS_LIVE_ORGANIZATION_ID to the uuid of the one to use, in the environment or in .env; the failure lists them.
Tests never touch the network except tests/test_transport.py (a local HTTP server) and tests/live (opt-in).
Everything else runs against an in-memory fake of the API.
Create a project. organization_id is needed only when the account belongs to several organizations, and the error will name them if so. A private project is visible to you alone; a normal one is visible to the whole organization.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| is_private | No | ||
| description | No | ||
| instructions | No | ||
| organization_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include destructiveHint=false, so the description adds value by explaining when organization_id is required and the error behavior, plus the visibility semantics of private vs normal projects. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main verb, and each sentence adds distinct contextual information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key creation nuances (org_id and privacy) but omits expected behavior like return value, permission requirements, or the purpose of the 'instructions' parameter. Given the sparse schema and annotations, it is functional but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates for organization_id (needed only in multi-org accounts) and is_private (visibility), but it provides no explanation for name, description, or instructions, leaving some parameters without added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Create a project,' a specific verb+resource that clearly distinguishes it from sibling tools like update_project or delete_project. It adds context about organization_id and project visibility, reinforcing its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for creating a new project and provides situational guidance for organization_id and is_private, but it does not explicitly mention when to use this tool over alternatives like update_project or list_projects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a scheduled task in a project. Omit cron_expression for a task that only runs when started by hand. cron_expression is five fields in UTC, not local time — '0 0 * * 1' is Monday 00:00 UTC. The answer carries next_run_at so the schedule can be checked before it matters. Relay any warning in the result to the user verbatim — it flags a model id claude.ai accepted without checking.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| model | No | ||
| prompt | Yes | ||
| project_id | Yes | ||
| cron_expression | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the single destructiveHint=false annotation: it clarifies the cron timezone is UTC, warns against local-time assumptions, reveals that the result contains next_run_at, and instructs relaying any warning verbatim. These are genuinely useful behavioral disclosures that are not available from the schema or annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences cover the core action, the most error-prone parameter, and a response-relay requirement without waste. The most important caveats are front-loaded, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description tells the agent what key response fields to expect (next_run_at and warning) and gives enough parameter guidance to make a correct first call. The sibling tool list provides surrounding context, and nothing essential to invoking the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the parameter-explanation burden. It thoroughly explains cron_expression—its five-field format, UTC semantics, an example, and how to omit it. Other parameters like project_id, name, prompt, and model are self-explanatory from their names, though model gets no additional guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a scheduled task in a project,' naming a specific verb, resource, and scope. This cleanly distinguishes it from sibling operations like update_scheduled_task, delete_scheduled_task, and list_scheduled_tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear conditional: omit cron_expression for a task that only runs when started by hand, implying the alternative is to include it for time-based schedules. It provides useful context but does not explicitly name alternative tools or state when not to use create_scheduled_task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a document, by uuid or by an unambiguous file name. The content is backed up locally first. A name shared by several documents is refused: pass the uuid to say which one.
| Name | Required | Description | Default |
|---|---|---|---|
| document | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses that content is backed up locally first and that ambiguous names are refused, adding safety and error-condition context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no redundant information; each sentence adds a distinct piece of information (action/identifiers, backup, ambiguity handling).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the action, identification methods, backup behavior, and ambiguity handling, but omits any explanation of the project_id parameter and does not describe success/error returns. Adequate for a simple tool but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that the 'document' parameter can be a uuid or unambiguous file name, but it does not explain the 'project_id' parameter at all. With 0% schema coverage, this leaves a gap for one of the two required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete a document) and the resource (document), with additional specificity about the two identifiers (uuid or unambiguous file name). This distinguishes it from sibling tools like delete_project and other document operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use uuid versus file name based on ambiguity, and notes the refusal behavior. It does not explicitly compare with alternative tools or state when not to use this tool, but it gives clear context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a project and everything in it. There is no server-side undo, so confirm_name must be set to the project's exact current name. Every text document and every file uploaded through the web UI is copied to the local backup directory first; if any of that fails, nothing is deleted. An upload with no downloadable original, such as an image, or one the listing gives no size for, blocks the deletion until it is removed in the web UI.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| confirm_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses no server-side undo, mandatory local backup, atomic failure behavior, and specific upload-related blockers. This is substantial behavioral context that an agent needs before invoking a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, each earning its place. The core destructive warning is front-loaded, followed by safety guarantees and edge-case blockers. No redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an irreversible destructive operation, the description covers preconditions, failure behavior, backup guarantees, and blocking edge cases. No output schema exists, so return-value documentation is not required. The description is sufficiently complete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It clearly explains that confirm_name must be set to the project's exact current name. project_id is not explicitly described but is inferable from the tool's purpose and parameter title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is explicit: 'Delete a project and everything in it' names the verb, the resource, and the scope of the deletion. This clearly distinguishes it from sibling delete tools that target documents or scheduled tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage context: confirm_name must match the exact project name, backup must succeed before deletion, and certain uploads block deletion. It does not explicitly compare against alternative tools, but the uniqueness of the resource makes that unnecessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a scheduled task. Unlike documents, nothing is backed up first — a task is a prompt and a schedule, not content — so prefer update_scheduled_task with enabled=false if you only want it to stop running. Relay any warning in the result to the user verbatim — it reports a task that was already gone.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses that there is no backup, that the task is just a prompt and schedule, and that the result may contain a warning about an already-deleted task that must be relayed verbatim. This is meaningful non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences deliver the core action, the key caution, the preferred alternative, and the warning-handling requirement with no filler. The most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive tool with no output schema, the description covers the important edge case (already-deleted task), the lack of backup, and the alternative. Nothing essential is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain task_id, its format, or how it identifies the target beyond the obvious property name. The single parameter is inferable, but the description itself adds no parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Delete a scheduled task.' It also differentiates itself from update_scheduled_task and document deletion, so an agent can clearly distinguish this from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent when not to use this tool: prefer update_scheduled_task with enabled=false if the goal is only to stop execution. It also notes that no backup is made, reinforcing that this is for permanent deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one project: its name, description, and instructions. Only this tool returns the instructions — list_projects does not carry them.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description does not need to restate safety. It adds that the tool returns name, description, and instructions, and that instructions are unique to this tool. While it does not mention permissions or error handling, for a read-only tool with readOnlyHint this is adequate context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler, front-loading the core action ('Read one project') and then adding a crucial distinguishing detail. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and a readOnlyHint annotation, the description covers the purpose, the returned content (name, description, instructions), and a key differentiation from list_projects. No output schema exists, but the description adequately communicates what is returned. A minor gap is the lack of error-case mention, but the core context is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter project_id with 0% description coverage. The tool description does not mention project_id at all, nor does it clarify how to identify the project. Given the low schema coverage, the description needed to compensate but did not, relying on the parameter name alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' with the resource 'one project' and explicitly differentiates itself from the sibling tool list_projects by noting that it is the only tool that returns instructions. This clearly states what the tool does and why it is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides an alternative and a condition for use: 'Only this tool returns the instructions — list_projects does not carry them.' This directly tells the agent when to choose this tool over a sibling, and implies when not to use it (for listing without instructions).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one scheduled task by its id, including the prompt it will send.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates this is a safe read operation, and the description adds useful behavioral context by noting the response includes the prompt the task will send. It does not contradict annotations, though it does not mention not-found behavior or response format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tightly worded sentence that front-loads the action, resource, and key return detail. Every word contributes meaning, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-one operation with one parameter and a readOnly annotation, the description is largely complete. It tells the agent what it reads and highlights the important return content. It could be more complete with error or not-found behavior, but this is not essential for basic correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one required parameter, task_id, with no schema-level description coverage. The description's phrase 'by its id' provides minimal semantic reinforcement, but it does not elaborate on the expected format, source, or meaning of the id beyond what 'Task Id' already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read'), a clear resource ('one scheduled task'), and a distinguishing detail ('by its id, including the prompt it will send'). This clearly differentiates it from list_scheduled_tasks, which lists tasks, and from create/update/delete operations on scheduled tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving a single scheduled task when its id is known, but it does not explicitly state when to prefer this over list_scheduled_tasks or when not to use it. Usage context is reasonable but left to inference rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the text documents in a project, and under uploaded_files the files uploaded through the web UI, such as PDFs, which count toward knowledge but are not documents: pull_documents copies them, push_documents sends a PDF, PNG, JPEG, GIF, or WebP file up as one, and delete_project backs them up, but nothing here can compact one. knowledge reports the project's size against its search threshold and its maximum. duplicate_file_names flags names held by more than one document, which happens when a save is interrupted; the next write_document with overwrite=true cleans them up. Relay any warning in the result to the user verbatim.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true, and the description adds substantial behavioral detail: uploaded_files count toward knowledge but are not documents, knowledge reports size against thresholds, duplicate_file_names flags interrupted saves, and warnings should be relayed verbatim. This goes far beyond what structured annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and packs several non-obvious behaviors into one run-on paragraph, but it is front-loaded with the primary purpose and every sentence contributes useful information about return fields or edge-case behavior. It could be tightened into clearer sections, but none of it is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the burden of explaining return values; it covers uploaded_files, knowledge, duplicate_file_names, and warning. It does not describe the exact per-document shape or pagination, but for a list operation with a single clear ID parameter this is a fairly complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero schema description coverage and only one parameter, the description should explain or contextualize project_id, but it never mentions it. The parameter name is self-evident, so the gap is not severe, but the description adds no parameter-level meaning beyond the schema's name and type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List the text documents in a project' and then clarifies that uploaded_files are distinct from documents. It differentiates from sibling tools by referencing pull_documents, push_documents, delete_project, and write_document, so an agent can tell exactly what this tool covers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context about when the tool is relevant, especially for inspecting both documents and uploaded files, and it relates other siblings to those uploaded files. It does not lay out an explicit 'use this tool instead of X' rule, but the distinctions it makes are enough to route an agent correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the claude.ai / Claude Cowork projects on this account, each tagged with the organization that owns it. Use this to find a project uuid.
| Name | Required | Description | Default |
|---|---|---|---|
| organization_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation. The description adds modest behavioral context by noting projects are tagged with their owning organization and scoped to 'this account,' but it does not disclose other traits like pagination, response format, or permission requirements. This is acceptable given the annotation, but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, with the verb and resource front-loaded in the first sentence and the use case in the second. Every word earns its place; there is no fluff or repetition of the tool name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter and no output schema, yet the description still leaves the organization_id parameter ambiguous. The core purpose and use case are clear, but the missing parameter semantics and lack of output format details mean the description is not fully complete for an agent to use it confidently in all scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one optional parameter, organization_id, with 0% schema description coverage. The description fails to explain the meaning or effect of this parameter, such as whether it filters projects by organization or retrieves all projects when null. This is a significant gap since the description was the only place to clarify the parameter's semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('projects') and scope ('on this account'), and further specifies the output includes the owning organization. It clearly distinguishes from siblings like get_project and list_documents, and states the intended purpose ('find a project uuid').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: 'Use this to find a project uuid.' This establishes when to use the tool, but it does not explicitly mention when not to use it or call out alternatives like get_project once the uuid is known. Still, the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Cowork scheduled tasks. Pass project_id for one project's tasks, or nothing for every task on the account. Schedules are cron expressions in UTC; a task with none runs only when started by hand. If the tasks cannot be matched to the project, every task in the organization is listed and warning says so; relay any warning to the user verbatim.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | ||
| organization_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint, so the description does the real work here. It discloses UTC cron semantics, the manual-run implication of missing cron, the fallback to organization-wide tasks, and the warning field that must be relayed verbatim. This goes well beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with no filler: action and scope first, then schedule behavior, then fallback and warning handling. Every sentence adds value and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the main behavior, fallback, and warning semantics well, but is incomplete for the full input schema because organization_id is never mentioned. With no output schema, the return shape is also left implicit, though the list behavior can be reasonably inferred.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains project_id and the no-argument case, but completely omits organization_id, which appears in the schema with no description. Since schema description coverage is 0%, the description was responsible for documenting all parameters and only covered one of two.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear action ('List') and specific resource ('Cowork scheduled tasks'), and distinguishes itself from sibling tools like get_scheduled_task by describing a list operation. Also clarifies the scope options, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives practical scoping guidance ('Pass project_id for one project's tasks, or nothing for every task on the account'), but it does not explicitly route the agent to alternatives such as get_scheduled_task for a single task or explain when not to use this tool. The usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy the project's documents and uploaded files into a local folder. Uploads such as PDFs come down as bytes, and each result row says which kind it was. Local files that differ are kept, not overwritten, unless overwrite_local=true.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| overwrite_local | No | ||
| destination_directory | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=false in annotations, the description carries most of the behavioral burden. It discloses useful details: local files that differ are kept, overwrite_local=true changes that, and uploads such as PDFs come down as bytes. This adds meaningful behavior beyond the annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with the primary action front-loaded. The second sentence adds essential nuance about bytes, kind, and overwrite behavior without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a copy/download operation, the description covers destination, overwrite behavior, uploaded-file handling, and result metadata. There is no output schema and only minimal annotations, so some detail about the exact return structure is absent, but the tool remains understandable and callable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clearly explains overwrite_local semantics and the meaning of the result rows' kind field. project_id and destination_directory are left self-evident from their names and the schema, which is acceptable given their intuitive roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Copy the project's documents and uploaded files into a local folder.' This clearly distinguishes pull_documents from sibling tools like push_documents or read_document, and the title is not needed to understand the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the core use case obvious: copying project documents to a local folder. It gives context about uploaded files coming down as bytes and the kind field, but it does not explicitly name alternatives or say when not to use this tool versus siblings like push_documents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a local folder's files into the project: a PDF, PNG, JPEG, GIF, or WebP file goes up as an uploaded file, the way the web UI adds one, and every other file, other image formats included, becomes a text document and must be UTF-8. The default pattern *.md matches no upload, so pass pattern='*' to send everything in the folder. Unchanged files are skipped, differing ones need overwrite=true (the replaced version is backed up locally first), and nothing remote that is missing locally is ever deleted. An uploaded image already in the project is left alone, since it offers no original to compare against or back up. Use dry_run=true to preview, including where the push would stop; that stop is an estimate, since a preview writes nothing to measure, and it cannot count uploads at all. Stops at the first file that would grow the project past its search threshold or its maximum (allow_search_mode=true accepts the threshold); files already pushed stay. Relay any warning in the result to the user verbatim.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | ||
| pattern | No | *.md | |
| overwrite | No | ||
| project_id | Yes | ||
| source_directory | Yes | ||
| allow_search_mode | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the full consequence profile well beyond the single destructiveHint:false annotation: unchanged files are skipped, overwritten versions are 'backed up locally first,' nothing remote is ever deleted, and dry_run 'writes nothing to measure' so its stop and upload counts are estimates. It even flags the counterintuitive edge case that existing uploaded images are left alone. All claims are consistent with the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Long but every sentence earns its place: purpose, file modes, pattern gotcha, change semantics, edge case, dry-run limitation, stop thresholds, and warning relay each appear exactly once with no filler. The core purpose is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 0% schema coverage, minimal annotations, and no output schema, the description must be self-sufficient, and it is: it covers file-type handling, overwrite/backup behavior, the no-deletion guarantee, dry_run accuracy limits, project-threshold stops, and even instructs relaying result warnings verbatim. Nothing an agent needs to invoke this correctly is left to guesswork.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden, and it delivers: it explains the pattern default trap ('The default pattern `*.md` matches no upload'), the overwrite prerequisite, dry_run's estimation limits, and allow_search_mode's effect on the search-threshold stop. Every parameter except the self-evident project_id and source_directory receives direct semantic explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: 'Send a local folder's files into the project,' then details the two file-handling modes (PDF/PNG/JPEG/GIF/WebP become uploaded files; everything else becomes a UTF-8 text document). The direction and bulk scope unmistakably distinguish it from the nearest sibling pull_documents, which is the reverse operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit invocation guidance: 'differing ones need overwrite=true,' 'Use dry_run=true to preview,' and 'pass pattern='*' to send everything in the folder,' plus when allow_search_mode is relevant. It never names an alternative tool or a when-not-to-use condition, so it falls short of a 5, but the context for correct parameter usage is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one document, by file name or uuid. If several documents share the name, the newest is returned and warning names the others; relay any warning to the user verbatim.
| Name | Required | Description | Default |
|---|---|---|---|
| document | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the safety profile is known. The description adds valuable behavioral detail: duplicate names resolve to the newest document, a 'warning' is emitted naming other matches, and the warning must be relayed verbatim to the user. This goes beyond annotations and provides actionable handling instructions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences; the first leads with the core action and the second is tightly scoped to an edge case and required user-facing action. No fluff or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with readOnlyHint, the description covers identifier formats and the key duplicate-name edge case with a specific instruction. It does not describe not-found behavior or return structure, but the operation is simple and the absence of an output schema lowers that requirement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description must compensate. It explains the 'document' parameter as accepting either a file name or uuid, which adds real meaning. However, 'project_id' is left unexplained beyond its title, so parameter semantics are only partially addressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Read one document') and clarifies the identifier formats accepted (file name or uuid). The duplicate-name warning behavior further distinguishes it from sibling tools like write_document or delete_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single document by name or uuid but offers no explicit guidance on when to choose this over siblings such as pull_documents or list_documents. There are no exclusions or alternative routing, so the agent must infer selection from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a document, by uuid or by an unambiguous file name. The content is re-created under the new name before the original is deleted, with local backups first, so nothing is lost midway. A new name already in use is refused unless overwrite=true, which replaces its holder (backed up first). Relay any warning in the result to the user verbatim.
| Name | Required | Description | Default |
|---|---|---|---|
| document | Yes | ||
| overwrite | No | ||
| project_id | Yes | ||
| new_file_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the destructiveHint annotation by explaining the safe rename sequence: content is re-created under the new name, the original is deleted only afterward, and local backups are made first. It also discloses overwrite behavior and instructs relaying warnings verbatim. This gives the agent a strong mental model of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no filler. It front-loads the core operation, then explains safety behavior, overwrite behavior, and warning handling in logical order. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is nearly complete for this tool: it covers how to identify the document, overwrite behavior, backup safety, and warning handling. The main gaps are no explicit mention of the project_id parameter's role and no detail about the success-return shape beyond warnings, both of which are minor given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for the bare parameter names. It adds useful meaning for 'document' (uuid or unambiguous file name) and 'overwrite' (replaces existing holder after backup), and implicitly defines 'new_file_name'. However, it does not explain 'project_id' or any file-name format constraints, leaving some parameter semantics to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Rename a document'. It also clarifies the identifier forms ('by uuid or by an unambiguous file name'), making the operation unambiguous. This clearly distinguishes it from sibling tools like read_document, write_document, and delete_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operating context: when the new name is already in use, overwrite=true is required, and it explicitly says refusal happens otherwise. It does not explicitly name alternative tools or state when not to use this tool, but the rename purpose is clear enough for an agent to select it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a project's name, description, or instructions. Only the fields you pass are touched; the rest keep their current values. Pass an empty string to clear one.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| project_id | Yes | ||
| description | No | ||
| instructions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=false, indicating non-destructive behavior. The description adds meaningful behavioral detail beyond this: partial updates and the ability to clear fields with an empty string. It does not mention permissions, return values, or error handling, but the mutation semantics are clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences deliver all essential information with no filler. The first sentence front-loads the core purpose, and the second provides critical partial-update/clearing behavior. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, but the description covers the main contextual needs: what fields can be changed, that updates are partial, and how to clear values. It omits return value/error behavior, but given the low complexity and the presence of destructiveHint=false annotation, the description is largely complete. A more explicit mention of whether an updated project object or just a status is returned would push it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by naming the three updatable fields (name, description, instructions) and clarifying their semantics: only passed fields are changed, and empty strings clear values. The required project_id is not described, but its role is implied by the tool name and schema, and the field-level semantics for the others are well explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific action verb and resource: 'Change a project's name, description, or instructions.' It clearly distinguishes update_project from sibling CRUD tools like create_project, get_project, and delete_project by naming the exact mutable fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: updating existing projects, with a partial-update semantic ('Only the fields you pass are touched'). It does not explicitly name alternatives or state when not to use it, but the sibling tool names and 'change' verb make the use case obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a scheduled task. Only the fields you pass are touched. Pass enabled=false to pause a task without losing its prompt or schedule, which is almost always better than deleting it. A schedule cannot be removed here — pause it instead. Relay any warning in the result to the user verbatim.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| model | No | ||
| prompt | No | ||
| enabled | No | ||
| task_id | Yes | ||
| cron_expression | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include destructiveHint=false, so the description carries the behavioral burden. It clearly explains partial updates, the semantics of enabled=false as pausing, the fact that schedules cannot be removed here, and instructs the agent to relay any warning from the result verbatim. This is rich, useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each carrying distinct value: partial-update semantics, pause-vs-delete guidance, schedule-removal limitation, and warning handling. The most important behavior is front-loaded, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter mutation tool with no output schema, the description covers the critical behavioral nuances and post-call responsibility (relaying warnings). It does not describe the full success return shape, but the warning instruction addresses the main non-obvious part of handling the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds important meaning to enabled=false as pausing, explains that unspecified optional fields are left untouched, and warns that cron_expression cannot be used to remove a schedule. The remaining parameters (name, model, prompt, task_id) are self-explanatory enough from their names, though not individually documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Change a scheduled task.' It adds the crucial partial-update semantic ('Only the fields you pass are touched') and implicitly differentiates this from the delete_scheduled_task sibling by explaining that pausing via enabled=false is preferable to deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: use enabled=false to pause instead of deleting, and do not attempt to remove a schedule through this tool—pause it instead. This directly addresses the main alternative and limitation, leaving no ambiguity about the key decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a document, or replace one with overwrite=true. The previous content is backed up locally before any replacement. Pass expected_uuid (from read_document) to refuse the write if a teammate has saved since you read it. Refused when the write would grow the project past its search threshold or its maximum, naming the documents most worth compacting and the largest uploaded files, which only the web UI can remove; allow_search_mode=true accepts the threshold, never the maximum. Relay any warning in the result to the user verbatim — it flags a leftover copy or a file name with no extension.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| file_name | Yes | ||
| overwrite | No | ||
| project_id | Yes | ||
| expected_uuid | No | ||
| allow_search_mode | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only destructiveHint:false as annotation, the description carries the full behavioral burden and delivers: pre-replacement local backup (reconciling with destructiveHint=false), refusal behavior when thresholds are exceeded, actionable refusal details, the web-UI-only limitation for removing uploaded files, and the instruction to relay any warning verbatim. No contradiction found between the description's 'replace' semantics and destructiveHint=false because the backup mechanism explicitly mitigates destructiveness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with the core action ('Create a document, or replace one with overwrite=true') and then adding only conditional and edge-case behavior. Every clause earns its place — safety backup, concurrency, refusal conditions, UI limitation, and warning relay — with zero filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-complexity tool (6 params, conditional refusal, concurrency guard, no output schema, minimal annotations), the description is remarkably complete. It covers the action, the failure modes and what they contain, the limitation, the exception flag, and the one return-field behavior (warning) the agent must act on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, requiring full compensation from the description. It explains the three non-obvious parameters clearly: overwrite (replacement mode), expected_uuid (optimistic-concurrency guard sourced from read_document), and allow_search_mode (threshold-acceptance, never maximum). The remaining parameters (content, file_name, project_id) are self-evident from their names, so their omission is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening clause 'Create a document, or replace one with overwrite=true' states a specific verb, resource, and exact mode condition. It naturally distinguishes this tool from siblings like read_document, rename_document, delete_document, and push/pull_documents without requiring schema inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description embeds clear conditional usage: overwrite=true for replacement, expected_uuid from read_document for concurrency safety, and allow_search_mode for the threshold-only exception. It references the read-then-write workflow via read_document. It stops short of explicit 'don't use when' statements or alternative routing, which keeps it at a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.5.0create_scheduled_taskdelete_scheduled_taskget_scheduled_tasklist_scheduled_taskspush_documents1 field changedInput schema / properties / allow_search_modeAdded value: +{
+ "default": false,
+ "title": "Allow Search Mode",
+ "type": "boolean"
+}update_scheduled_taskwrite_document1 field changedInput schema / properties / allow_search_modeAdded value: +{
+ "default": false,
+ "title": "Allow Search Mode",
+ "type": "boolean"
+}v0.2.1rename_documentv0.1.0create_projectdelete_documentdelete_projectget_projectlist_documentslist_projectspull_documentspush_documentsread_documentupdate_projectwrite_documentScored across 17 tools
Every tool targets a distinct resource-action pair: projects, documents, and scheduled tasks each have separate create/read/update/delete/list or equivalent operations. Even similar-sounding tools like read_document vs list_documents have clearly differentiated behaviors, with no overlapping purposes.
All tool names follow the verb_noun snake_case pattern consistently: list_projects, get_project, update_project, read_document, write_document, push_documents, etc. The only pluralization (list_* tools take plural nouns) follows a predictable list-versus-singular convention.
17 tools is slightly above the typical well-scoped range, but the count is justified by covering three distinct resource types (projects, documents, scheduled tasks) with near-complete lifecycle operations. Each tool serves a clear need and the set remains navigable.
The tool surface is comprehensive for the domain: projects have full CRUD, documents cover read/write/rename/delete/list/pull/push, and scheduled tasks have create/read/update/delete/list. Edge cases like overwrite safety, local backups, and search threshold handling are baked into descriptions, leaving no obvious dead ends.
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
Give Claude only the Google Drive files you choose. Every action logged.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
