This MCP server gives Claude Code read/write access to Claude Cowork / claude.ai projects, their knowledge documents, and scheduled tasks from the terminal.
Manage projects: list them across organizations, fetch full details including instructions, create, update, and delete (with exact-name confirmation and local backup of everything inside).
Manage documents: list, read, write, rename, and delete text documents, with overwrite protection, local backups, duplicate-name warnings, and optional expected_uuid concurrency checks.
Copy content locally: pull a project's documents and uploaded files (e.g. PDFs) into a local folder, and push local text documents into a project with dry-run, pattern, and overwrite controls.
Manage scheduled tasks: list tasks for one project or the whole account, get task details, create with optional cron schedules (UTC), update or pause tasks, and delete them.
Enforce knowledge capacity: list_documents reports usage; writes that would exceed the search threshold or maximum are refused, with allow_search_mode permitting only the threshold.
Handle uploaded files: they are listed, counted toward knowledge size, and downloaded/backed up, but cannot be written or pushed from this server.
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 465 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, and backed up before a deletion, but that path is built against a captured response shape and has not yet been run against a real upload (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 has a preview and a thumbnail, which are renditions, so it is listed but can be neither pulled nor backed up.
Nothing here can upload one.
The endpoint the web UI uses for that has not been observed, so push_documents carries text documents only.
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 download path has not been run against a real upload.
Listing, pull_documents, and the pre-delete backup are built against the captured listing shape and the in-memory fake; 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.
Run them with CLAUDE_PROJECTS_LIVE_TESTS=1 against an account holding a PDF before trusting a pull or a deletion with uploads in it.
Uploaded files cannot be written from here. Adding or replacing a PDF means the web UI until the upload endpoint is observed, and a pull-and-push copy therefore carries the documents only.
Uploads that are not documents cannot be read either.
An image offers only a preview and a thumbnail, 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; only a PDF has been observed so far, so what other kinds offer is unknown.
An upload that is itself an HTML file would be refused the same way, since the download path treats an HTML body as a login page served in place of the file.
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.
Capacity refusals rank documents only.
capacity.py cannot name an upload worth removing, so a project that is full because of uploads is told to compact the wrong things, or that there is nothing else to compact; list_documents at least shows the uploads with their sizes.
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 |
| Upload a local folder's text documents into a project (gated by knowledge capacity); uploaded files cannot be pushed (see To do) |
| 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 named as compaction candidates, because only the web UI can remove one (see To do).
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, but push_documents cannot send them back, so a pull-and-push copy carries the documents only (see To do)
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 .Tests never touch the network except tests/transport (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 and delete_project backs them up, but nothing here can write or compact them. 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?
Even though readOnlyHint=true already signals safety, the description adds substantial behavioral detail: uploaded_files count toward knowledge but are not documents, nothing here can write or compact them, duplicate_file_names appears after interrupted saves, and warnings must be relayed to the user 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?
The description is a dense, run-on paragraph with multiple nested clauses, colons, and asides. While informative, it is not concise or well-structured; key points such as warning relay and duplicate_file_names are packed into the middle and end rather than cleanly 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?
With no output schema, the description does a good job of describing important result fields: uploaded_files, knowledge, duplicate_file_names, and warning. It also explains relationships to other tools. It is not exhaustive about the document object structure, but it provides enough context for an agent to call and interpret the tool 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 only parameter, project_id, is never described beyond the generic phrase 'in a project'. The description does not compensate for the missing schema documentation with any format, source, or usage details for the parameter.
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'. It further distinguishes itself from siblings by clarifying that uploaded_files are not documents baseline, that pull_documents copies them, and that write_document handles duplicate cleanup.
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 and exclusions: 'nothing here can write or compact them', pull_documents copies uploaded files, delete_project backs them up, and write_document with overwrite=true cleans duplicates. It does not explicitly say 'use this when you need to enumerate documents', but the alternative behaviors are clearly attributed.
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.
Upload a local folder's text files into the project. Unchanged files are skipped, differing ones need overwrite=true, and remote documents missing locally are never deleted; the project's uploaded files are untouched and cannot be pushed. Use dry_run=true to preview. 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?
Beyond the single destructiveHint:false annotation, the description discloses skipped unchanged files, overwrite requirements, the never-delete guarantee, threshold behavior, error-stop semantics, and the need to relay warnings. This is rich behavioral context that materially affects how an agent should run and handle the result.
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 paragraph is dense but every sentence adds operational value, and key behaviors are front-loaded before edge cases. It is slightly monolithic and has minor overlap between 'remote documents missing locally are never deleted' and 'the project's uploaded files are untouched', but it remains efficient.
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 complex six-parameter tool with no output schema, the description covers preview mode, overwrite handling, deletion safety, size-limit aborts, persistence of already-pushed files, and verbatim warning handling. These are exactly the conditions an agent needs to predict before invoking the tool.
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 explaining dry_run, overwrite, allow_search_mode, project_id, and source_directory. The pattern parameter is only implicitly covered via the 'text files' wording and the default '*.md', but no explicit glob/filter semantics are given.
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, upload local text files into a project, and clearly distinguishes the direction from pull_documents. It also establishes scope boundaries ('the project's uploaded files are untouched and cannot be pushed'), so an agent understands exactly what this tool does and does not do.
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?
It gives concrete parameter guidance: use dry_run=true to preview, set overwrite=true for differing files, and use allow_search_mode=true to accept the threshold. It also states an exclusion, that project-uploaded files cannot be pushed, but it does not explicitly name sibling tools or say when to prefer write_document/pull_documents.
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; 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?
Beyond the sparse annotations (only destructiveHint=false), the description discloses backup-before-replace, optimistic concurrency refusal via expected_uuid, refusal conditions for search threshold/maximum, the exact allow_search_mode semantics, and the need to relay any warning. This is exceptionally transparent for a mutating tool.
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 but every sentence earns its place: core action first, then safety, concurrency, refusal conditions, and result handling. It uses efficient semicolon-separated clauses rather than padded prose, and the most important usage 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?
With no output schema, the description still tells the agent how to handle a key part of the result ('Relay any warning in the result to the user verbatim') and enumerates all refusal modes. For a 6-parameter mutation tool, this covers the non-obvious behavior an agent needs to call it successfully.
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 carry the semantic load. It does: overwrite is defined as replace behavior, expected_uuid is explained as a concurrency guard, and allow_search_mode is precisely distinguished (accepts threshold, never maximum). Even the file-name-without-extension warning adds parameter-adjacent meaning beyond the schema titles.
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 precise verb and resource: 'Create a document, or replace one with overwrite=true.' It clearly separates create vs replace and stands apart from siblings like read_document, rename_document, and delete_document by describing the write/update action. No ambiguity about what the tool does.
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?
It gives clear when-to-use context (create a new document, or replace an existing one) and even points to read_document for expected_uuid. It stops short of explicitly contrasting with alternatives such as rename_document or delete_document or stating when not to use this tool, so it earns a 4 rather than a 5.
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
Each tool targets a distinct resource (projects, documents, scheduled tasks) and action (list, get, create, update, delete, etc.). There is no ambiguity between tools within the same resource group, and cross-resource tools are clearly separated by naming.
All tool names follow a consistent verb_noun pattern (e.g., list_projects, create_project, read_document, delete_scheduled_task). The naming is predictable and adheres to the same convention throughout, making it easy to infer functionality.
With 17 tools, the server sits slightly above the ideal 3-15 range, but each tool serves a distinct and necessary purpose within the three resource domains (projects, documents, scheduled tasks). The count is justified and not bloated.
The tool surface provides full lifecycle coverage for all three resource types: projects have complete CRUD operations, documents support list/read/write/rename/delete plus sync operations (pull/push), and scheduled tasks have full CRUD. There are no obvious gaps that would hinder agent workflows.
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.
Your Aurentia workspace — projects, CRM, tasks, deliverables — in Claude, Cursor or any MCP client.
