Rename or move a file inside a Typst project by providing the project ID, existing file path or ID, and new destination path.
Rename or move a file inside a https://typst.app project via UpdatesFileMutation.
| Name | Required | Description | Default |
|---|---|---|---|
| newName | Yes | New destination path/name inside the project | |
| filePath | Yes | Existing file path/name or file ID | |
| projectId | Yes | The Typst project ID |
Changes observed during successful MCP inspections.
v1.0.2Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and only adds an internal implementation detail (UpdatesFileMutation). It does not disclose whether an existing destination file is overwritten, whether new directories are created, permission/auth requirements, or what the mutation returns — material gaps for a mutation 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?
A single front-loaded sentence with no filler. The trailing 'via UpdatesFileMutation' is the only element of dubious value to an agent.
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?
A three-required-parameter mutation with no annotations and no output schema needs more: overwrite behavior, error conditions on missing source or colliding destination, and expected result are all unaddressed. The description is too thin for the tool's complexity.
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 100%, so all three parameters (projectId, filePath, newName) are already documented in the schema. The description adds no format or path semantics beyond that baseline, which is acceptable given the schema does the work.
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 pair (rename or move) and resource (a file) scoped to a Typst project, which is clear enough for an agent to distinguish it from read/write/delete file siblings. It stops short of naming or contrasting those siblings explicitly.
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 rename/move framing implies when the tool applies versus typst_write_file or typst_edit_file, but no explicit when-to-use, prerequisites, or alternative routing is given. Usage must be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.