Skip to main content
Glama

Make a folder

folder
Idempotent

Create named document directories with icons, colors, and optional nesting; reuse an existing name to retrieve or restyle it.

Instructions

Make a folder for documents (tasks go in lists), with an icon and colour if they fit. A name in use hands back that folder, found at any depth unless inside says where; an icon or colour sent restyles it.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>"
    },
    "name": "folder"
  }
}

Input Schema

NameRequiredDescriptionDefault
iconNoOne emoji, or a drawn name: home, work, money, study, travel, health, food, family, code and the like
nameYesIts own name, a word or two, at most 40 characters; a path only to say where to nest it, every step but the last existing
colorNored, orange, amber, green, teal, blue, indigo, purple, pink, brown or gray
insideNoAn existing folder to nest it in, by name, path or id; four deep at most

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.43.2
    • changedInput schema / properties / icon / description
      Previous value: -"A single emoji, or one name from the drawn catalogue: home, work, money, study, travel, health, food, family, code and the like. An emoji is often the plainer choice"New value: +"One emoji, or a drawn name: home, work, money, study, travel, health, food, family, code and the like"
    • changedInput schema / properties / inside / description
      Previous value: -"An existing folder to nest it in, by its name, its whole path or its id. Four deep at most"New value: +"An existing folder to nest it in, by name, path or id; four deep at most"
    • changedInput schema / properties / name / description
      Previous value: -"A word or two, at most 40 characters. It is the folder's own name, never a path: send the whole path only to say where to nest it, and then every step but the last has to exist already"New value: +"Its own name, a word or two, at most 40 characters; a path only to say where to nest it, every step but the last existing"
  2. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations declare idempotentHint=true and destructiveHint=false, but the description explains what idempotency actually means: 'A name in use hands back that folder, found at any depth unless `inside` says where'. It further discloses that supplying icon or colour restyles an existing folder — a side effect the annotations do not convey — turning a create call into a possible upsert-modify.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the purpose, with the upsert semantics second. The phrasing is telegraphic in places ('A name in use hands back that folder'), but no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a four-parameter create tool with full schema descriptions and no output schema, the description covers purpose, the list/folder boundary, idempotent match behaviour, nesting scope and styling side effects. It does not say what the call returns (folder name, id, path), which is the one gap an agent must resolve empirically.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already defines each field, but the description adds the crucial interaction rule: an existing name is matched at any depth unless `inside` narrows the location, and icon/colour act as restyle triggers rather than create-only values. That is meaning beyond the schema's per-field text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Make a folder for documents') and immediately draws the boundary with a sibling concept: 'tasks go in lists'. An agent can tell whether it needs a folder or a list without opening the schema, and the name/title alone ('folder') would not have been enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the condition for creating a folder ('for documents') and opposite it against lists for tasks, which is clear context for use. It does not name the actual sibling tool 'lists' as the alternative, nor does it cover what to do when a folder already exists beyond the implicit restyle path.

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