Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses partial-update semantics ('lo que se omite no cambia'), that parentId=null moves the folder to the project root, and the cycle constraint preventing a folder from being moved into itself or a subfolder. It does not mention permission requirements or what the call returns, but it gives substantive behavioral context that the destructiveHint/idempotentHint flags alone do not convey.

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 create/update distinction is front-loaded, then per-mode parameter rules, then constraints, then the sibling pointer. Every sentence carries information; nothing is redundant.

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 mutation tool with 0% schema coverage and no output schema, the description covers modes, required/optional parameters, and key constraints. The remaining gap is that it does not indicate what the call returns (e.g. the created folder's id), which matters for a create operation.

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 load and does so: id selects create vs update, name is required on create and renames on update, projectId scopes creation, and parentId moves the folder with null meaning root. Nearly every parameter's meaning and conditional requirement is 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 names a specific resource and enumerates both operational modes: creating a doc folder when there is no id, renaming/moving it when an id is supplied. It also explicitly separates itself from the sibling save_doc, which is the tool used to place a document inside a folder.

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 states when to use each mode (sin id vs con id), which parameters are mandatory per mode (projectId and name on create), and which are optional (parentId). It also names the alternative tool for a related but different task (save_doc with folderId) and notes the self-move restriction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.